^GEM 

FROM DIGITAL RESEARCH 



GEM 



TM 



Virtual Device 
Interface Reference Guide 



Virtual Device Interface 
Reference Guide 



Software Version: 2.0 



5074-2023-101 



COPYRIGHT 

Copyright ©1986 Digital Research Inc. All rights reserved. No part of this publication 
may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated 
into any language or computer language, in any form or by any means, electronic, 
mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written 
permission of Digital Research Inc., 60 Garden Court. P.O. Box DRI, Monterey, California 
93942. 



DISCLAIMER 

DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH 
RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED 
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. 
Further, Digital Research Inc. reserves the right to revise this publication and to make 
changes from time to time in the content hereof without obligation of Digital Research 
Inc. to notify any person of such revision or changes. 



NOTICE TO USER 

This manual should not be construed as any representation or warranty with respect to 
the software named herein. Occasionally changes or variations exist in the software 
that are not reflected In the manual. Generally, if such changes or variations are known 
to exist and to affect the product significantly, a release note or READ. ME file 
accompanies the manual and distribution disk(s). In that event, be sure to read the 
release note or READ.ME file before using the product. 



TRADEMARKS 

Digital Research and its logo are registered trademarks of Digital Research Inc. GEM, 
Desktop, Graphics Environment Manager, the GEM logo, GEM Draw, GEM Output, 
CP/M-68K, and Concurrent are trademarks of Digital Research Inc. IBM is a registered 
trademark of International Business Machines, Corp. Intel is a registered trademark of 
Intel Corporation. Motorola is a registered trademark of Motorola Inc. Polaroid is a 
registered trademark of Polaroid Corporation. 

First Edition: June 1986 



Foreword 



This guide is intended for microcomputer application programmers 
with operating system and graphics programming experience. It 
describes the GEM^*^ Virtual Device Interface (VDI) features, operation, 
and applications interface. The GEM VDI provides a device- 
Independent environment In which to write graphics applications that 
can run under the most widely used operating systems. 

GEM VDI provides a device-Independent software interface for your 
application programs. You do not need to rewrite applications for use 
with different output devices such as screens, printers, and plotters. 
GEM VDI handles device differences, making it possible for you to send 
information to the devices through the application program as If the 
devices were the same. GEM VDI handles graphics requests and 
supplies the right driver to run the specific device. The GEM VDI 
specifies the calling sequence to access device driver functions as 
well as the necessary calling parameters. 

The GEM VDI package contains drivers for many of the most popular 
microcomputer-related graphics devices. 

You can write application programs in assembly language or in a 
high-level language that supports the GEM VDI calling conventions. 
You can compile or assemble and link programs containing GEM VDI 
calls in the normal manner. 

This guide contains nine sections, seven appendices, and an index. 

• Section 1 Introduces the GEM VDI. 

• Section 2 describes GEM VDI operating procedures, lists the 
functions that the VDI requires for each device, and details the 
VDI calling conventions. 

• Sections 3 through 9 describe the various GEM VDI functions. 

• Appendix A lists and describes the GEM VDI error messages. 

• Appendix B describes the format of a metafile. 



Ill 



• Appendix C describes the reserved metafile sub-opcodes. 

• Appendix D defines the GEIVI VDI standard Iceyboard. 

• Appendix E describes entry into the GEIVI VDI for specific 
operating systems and microprocessor-specific calling 
procedures. 

• Appendix F describes the system font character sets and the font 
file format. 

• Appendix G describes the format of a bit image file. 

The function reference table at the end of this guide lists the GEM VDI 
functions according to their opcode number and gives their respective 
C binding procedure names. 

Note that throughout the remainder of this guide the term "VDI" is 
used to refer to the GEM Virtual Device Interface. 
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SECTION 1 
Overview 



The GEM VDI provides graphics primitives for implementing graphics 
applications with reduced programming effort. Application programs 
interface to the VDI through a standard calling sequence. Drivers for 
specific graphics devices translate the standard VDI calls into the 
unique characteristics of each device. In this way, the VDI provides 
device independence. 

The GEM VDI consists of two components: the Graphics Device 
Operating System (GDOS) and the device drivers and their associated 
font files. 

The GDOS contains the device-independent graphics functions, while 
the device drivers and font files contain the device-dependent code. 
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Graphics Device Operating System 

The GDOS contains the basic host and device-independent graphics 
functions that can be called by your application program. Your 
application program accesses the GDOS in much the same way that it 
accesses the operating system. 

The GDOS performs coordinate scaling so that your application can 
specify points in a normalized space. It uses device-specific 
information to transform coordinates into the corresponding values for 
a particular graphics device. 

An application can also specify points in raster coordinate space, in 
which case no transformation occurs. 

Device Drivers 

The graphics device drivers are similar to the drivers in any I/O 
system. They contain the device-specific code required to interface 
particular graphics devices to the GDOS. The device drivers 
communicate directly with the graphics devices. The VDI requires a 
unique device driver for each graphics device in the system. 

The GEM VDI package contains drivers for the most popular 
microcomputer graphics devices, including screens, printers, plotters, 
and special cameras. 

A single program can use several graphics devices; the GDOS loads 
only the appropriate device driver file into memory. By referring to 
devices with a device identification number, an application program 
can send graphics information to any one of several memory-resident 
device drivers. 

A device driver produces graphics primitives according to the inherent 
capabilities of a particular graphics device. In some cases, a device 
driver emulates standard capabilities not provided by the graphics 
device hardware. For example, some devices require that dashed lines 
be simulated by a series of short vectors generated in the device 
driver. 

See "Required Functions" in Section 2 for a list of the functions that 
the VDI requires each driver to support. 
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Opcodes 

Each VDI function is associated witli an operation code (opcode). A 
calling routine indicates the graphics function to be performed by a 
device driver by specifying the function's opcode. 

References to VDI functions in this document include the function's 
opcode in hexadecimal notation; for example, "v_opnwk (1H)" refers to 
the Open Workstation function, whose opcode is one. 

Metafiles 

A metafile is the stored generic form of a picture file. Any VDI 
application can create a GEM VDI metafile that can later be called into 
another graphics application. The metafile driver stores a description 
of a picture in a data file. These files can later be sent to any device 
or used to exchange a picture between two compatible applications. 

When the VDI creates a metafile, it provides the ideal device (one with 
square pixels). Although their origins are different. Normalized Device 
Coordinates (NDC) and Raster Coordinates (RC) have the same range (0 
to 32767). No coordinate transformation is applied. "Coordinate 
Systems," later In this section, offers more information on the 
coordinate spaces. 

Refer to Appendix B for information about the metafile format. 

Device Handles 

Because the VDI allows multiple workstations to be open at the same 
time, each VDI function must be provided with a unique reference to 
the desired device. This identification is an signed WORD value 
referred to as the device handle. 

The GDOS returns the device handle when an application calls 
v_opnwk (1H), the Open Workstation function, or v_opnwvk (64H), the 
Open Virtual Workstation function. Routines that make subsequent 
calls to select a previously opened device must supply the device 
handle as an input argument. 
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The Assignment File, ASSIGN.SYS 

The ASSIGN.SYS file lists the device driver filenames, their associated 
font filenames, device identification numbers, and any device-specific 
information. ASSIGN.SYS is a text file that can be created or edited 
using any text editor. Device ID numbers are assigned according to 
their type; Table 1-1 lists the device ID numbers. 

The GDOS parses ASSIGN.SYS to create the assignment table, which it 
stores in memory to reference whenever an open workstation function 
is called. 

You can include the R command in ASSIGN.SYS to make a driver 
memory resident. To do so, place "R" after the device identification 
number of the driver you want resident. See the example that follows 
Listing 1-1. The opening comments in Listing 2-1 also include an 
example. 

Table 1-1. Device Identification Numbers 



Device Type 


Device ID 


Screen 


01-10 


Plotter 


11-20 


Printer 


21-30 


Metafile 


31-40 


Camera 


41-50 


Tablet 


51-60 



Device Driver Filename 

A device driver filename contained in ASSIGN.SYS must follow specific 
naming conventions: 

• It must have eight or fewer characters 

• Its first character must be alphabetic 

• The file's extension must be SYS 
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Sample ASSIGN.SYS 

Listing 1-1 shows the format of ASSIGN.SYS. 

Listing 1-1. Sample ASSIGN.SYS 

21 printer. sys 

;coniments, if desired 

fontl.fnt ;font1 description 

font2.fnt ;font2 description 

font3.fnt ;font3 description 

01 screen. sys 

;coniments. If desired 

font4.fnt ;font4 description 

fonts. fnt ;font5 description 

11 pi otter. sys 

; comments. If desired 

fonts. fnt ;font6 description 

font?, fnt ;font7 description 



If included in the ASSIGN.SYS file, the following command would make 
the screen driver memory resident: 

OIR screen.sys 

The VDI Entry Point 

The VDI specifies the calling sequence and required parameters for 
access to the device driver functions. 

The main entry point into the VDI is a single subroutine with five 
arguments, in the form of five arrays: 

• the control array 

• the array of integer input parameters 

• the array of Input point coordinates 

• the array of integer output parameters 

• the array of output point coordinates 

All array elements are WORD integers (two bytes). All arrays are zero- 
based. The content of the input and output parameter arrays is 
function dependent, and is included in the description of each function. 
"Function Parameters" in Section 2 contains more complete 
information about the format of the VDI function parameters. 
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See Appendix E for more detailed information about the 
microprocessor- and operating system-specific entry points into the 
VDI. 

Coordinate Systems 

All computer graphics are displayed using a coordinate system. The 
VDI verifies that the coordinate system of one device matches the 
coordinate system of another. 

You can address the display surface using one of two coordinate 
systems: 

• Normalized Device Coordinates (NDC) 

• Raster Coordinates (RC) 

The transformation mode, which the calling routine specifies when it 
opens a workstation, determines which coordinate system the 
application is to use. 

Normalized Device Coordinates— Transformation Mode 

In the NDC system, coordinates range from 0,0 ( lower left corner) to 
32767,32767 (xmax,ymax in the upper right corner). The NDC system 
addresses the graphics display in units that are independent of the 
device coordinate size. These units are then transformed to Raster 
Coordinates by the GDOS when an application specifies transformation 
mode 0. 

The full scale of NDC space (0-32767) Is mapped to the full 
dimensions of the device on both axes. On a nonsquare display with 
square pixels, a different scale factor is applied to each axis with this 
transformation mode. 

When transforming from NDC to RC, the GDOS assumes a raster 
coordinate at the lower left edge of a pixel. You should compensate 
for a boundary condition created at the top edge of NDC space. 

For example, suppose that the NDC point (32767, 32767) maps to the 
RC point (0, 200). Because pixels are addressed at their lower left 
corner, the NDC point (32766, 32766) would map to the RC point (1, 
199). You should correct for this boundary error by adding half of the 
NDC height and width into the coordinate transform to ensure that any 
roundoff error in the application-world-to-NDC transform does not 
cause the wrong pixel to be addressed. 
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Raster Coordinates — Transformation Mode 2 

Raster Coordinates (RC) are actual device units (for example, pixels for 
screens and steps for plotters and printers). Unlike the NDC system, 
RC system coordinates begin in the upper left corner; the lower right 
corner (xmax,ymax) addresses the bottom right pixel of the space. 
Figure 1-1 shows a comparison of the NDC and RC systems. 

The GDOS does not transform coordinates when the RC system is in 
effect. The application needs to adjust its coordinate transformation 
based on the aspect ratio of the device. 

The RC system eliminates the overhead involved when the GDOS 
transforms every point. 

See the Introduction to GEM Programming for more information on 
coordinate system transformations. 



0. 32767 



0.0 



x-1. 



X = Total number of pixels 
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y = Total number of pixels 
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0.0 32767. 
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0. y-1 



Raster Coordinates 



Figure 1-1. Normalized Device Versus Raster Coordinates 



End of Section 1 
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Function Summary and Calling Conventions 



This section explains how to use VDI functions in your graphics 
applications. 

The vol allows you to write graphics applications in assembly 
language or a high-level language (C language bindings are provided). 
Assembly language routines address VOI functions by opcode numbers. 
C language routines address VDI functions by procedure name. 

The VDI functions, described in sections 3 through 9, are grouped Into 
the following categories: 



Control 



Output 



Attribute 



These functions open and close the graphics 
workstation, set default values for device 
attributes, load and unload fonts, clear and update 
the display surface, and enable or disable 
rectangle clipping. 

The output functions write text strings and draw 
output items such as lines between two or more 
points, a marker at one or more points, and filled 
areas. The output functions also provide graphics 
drawing primitives to produce bars, arcs, circles, 
ellipses and elliptical segments, rounded 
rectangles, and justified text. 

The attribute functions control the writing mode 
(how items are imposed over existing pixel 
values) and determine the characteristics of the 
output functions. The output function 

characteristics determined by the attribute 
functions include color, line type, marker type, fill 
pattern and style, and character height. 
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Raster Operation 



Input 



Inquire 
Escape 



These functions operate on bit bloclcs in memory 
and on pixel blocl(s on physical devices. Raster 
operation functions copy bloclcs, determine the 
copy mode (how blocks are imposed over existing 
pixel values), transform block formats, and set 
color values for specified pixels. 

The input functions set the input mode to either 
request (wait for an input event) or sample (return 
input device status or location) and control the 
input devices. Input functions also set, show, or 
hide the cursor; sample the mouse button and 
keyboard states; and exchange the timer interrupt 
button change, mouse movement, and cursor 
change vectors. 

The inquire functions return the current attribute 
settings for the output items, information about 
the text faces, cell definitions, and input mode. 

These are device dependent control functions. 
For example, they can be used to control the 
cursor on an alpha screen, set the film type on a 
camera, and change the name of a metafile. 



Required Functions 

Each device type requires certain functions. Table 2-1, below, lists all 
of the VDI functions and indicates which devices are required to 
support them. Each device driver recognizes all opcodes, whether or 
not the driver supports the function. If an opcode is out of range, the 
driver performs no action. 

Because metafiles are transportable to any device, they are required to 
support all those functions common to any device you may use. See 
Appendix B for descriptions of the metafile format, metafile support of 
the inquiry functions, and metafile sub-opcodes. 
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You can determine if a function is available in a specific driver in one 
of the following ways: 

• Check the information about available features returned from 
Open Workstation, v_opnwk (IH), or Extended Inquire, vq_exntd 
(66H). 

• Check the values that a function returns for the length of the 
integer output and output point coordinate arrays. If zero is 
returned where non-zero values are indicated, the driver does not 
support the function. 

• Check the values returned from a function against the values 
specified in the call. If the two values are not the same, then 
either the driver does not support the function or the requested 
value is not available and the VDI selected a best fit value. 
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Table 2-1. Required VDI Functions 



Function (Opcode) 



Screen Printer Plotter Metafile Camera 



Open Workstation, v.opnwk (IH) X 

Close Workstation. v_clswk (2H) X 

Clear Workstation, v.clrwk (3H) X 

Update Workstation, v.updwk (4H) X 

Inquire Addressable Character Cells, 

vq_chcells (5-1 H) X 

Exit Alpha Mode, v.exitcur (5-2H) X 

Enter Alpha Mode. v_entercur (5-3H) X 

Cursor Up, v_curup (5-4H) X 

Cursor Down, v_curdown (5-5H) X 

Cursor Right, v.curright (5-6H) X 

Cursor Left. v_curleft (5-7H) X 

Home Cursor, v.curhome (5-8H) X 

Erase to End of Screen, v_eeos (5-9H) X 

Erase to End of Line, v_eeol (5-AH) X 

Direct Cursor Address, 

v_curaddress (5-BH) X 

Output Cursor Addressable Text, 

v_curtext (5-CH) X 

Reverse Video On, v_rvon (5-DH) 

Reverse Video Off, v_rvoff (5-EH) 

Inquire Current Alpha Cursor Address, 

vq_curaddress (5-FH) X 
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Table 2-1. Required VDI Functions (Cont'd) 

Function (Opcode) Screen Printer Plotter Metafile Camera 

Inquire Tablet Status, 
vq_tabstatus (5-10H) 

Hard Copy, v_hardcopy (5-1 1H) 

Place Graphic Cursor, v_dspcur (5-1 2H) X 

Remove Last Graphic Cursor, 

v_rmcur (5-1 3H) X 

Form Advance, v_form_adv (5-1 4H) X X 

Output Window, 

v_output_window (5-1 5H) X X 

Clear Display List, 

v_clear_dispjist (5-16H) X X 

Output Bit Image File, 

v_bitJmage (5-1 7H) X XX 

Inquire Printer Scan Heights, 

vq_scan (5-1 8H) X 

Output Printer Alpha Text, 

v_alpha_text {5-19H) X X 

Select Palette, vs_palette (5-3CH) 

Generate Tone, v.sound (5-3DH) X 

Set/clear Muting Flag. vs_mute (5-3EH) X 

Select Camera Film Type and Exposure, 

vsp_film (5-5BH) X 

Inquire Camera Film Name, 

vqp_filmname (5-5CH) X 

Disable/Enable Film Exposure, 
vsc_expose (5-5DH) 
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Table 2-1. Required VDI Functions (Cont'd) 



Function (Opcode) 




Screen 


Printer 


Plotter 


Metafile 


Camera 


Update Metafile Extents, 
v_meta_extents (5-62H) 










X 




Write Metafile Item, v_write_meta (5-63H) 






X 




Change GEM VDI Filename, 
vm.filename (5-64H) 










X 




Polyline, vjine (6H) 




X 


X 


X 


X 


X 


Polymarker, v_pmarl(er (7H) 




X 


X 


X 


X 




Text, v_gtext (8H) 




X 


X 


X 


X 




Filled Area, v.fillarea (9H) 




X 


X 


X 


X 




Cell Array, v.cellarray (AH) 














Bar GDP. v_bar (B-1H) 




X 


X 


X 


X 


X 


Arc GDP, v_arc (B-2H) 




X 


X 


X 


X 


X 


Pie Slice GDP, v_pieslice (B-3H) 




X 


X 


X 


X 


X 


Circle GDP, v.circle (B-4H) 




X 


X 


X 


X 


X 


Ellipse GDP, v_elllpse (B-5H) 




X 


X 


X 


X 


X 


Elliptical Arc GDP, v.ellarc (B-6H) 




X 


X 


X 


X 


X 


Elliptical Pie Slice GDP, v_ellpie (B- 


■7H) 


X 


X 


X 


X 


X 


Rounded Rectangle GDP, v_rbox (B 


-8H) 


X 


X 


X 


X 


X 


Filled, Rounded Rectangle GDP, 
v_rfbox (B-gH) 




X 


X 


X 


X 


X 



Justified Graphics Text GDP, 
vjustified (B-AH) 
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Table 2-1. Required VDI Functions (Cont'd) 

Function (Opcode) Screen Printer Plotter Metafile Camera 

Set Character Height Absolute Mode, 

vst_height (CH) X X X X X 

Set Character Baseline Vector, 
vst.rotation (DH) 

Set Color Representation, vs_color (EH) 

Set Polyline Line Type, vsLtype (FH) 

Set Polyline Width, vsLwidth (10H) 

Set Polyline Color Index, vsLcolor (11H) 

Set Polymarker Type, vsm_type (12H) 

Set Polymarker Height, vsm_height (13H) X 

Set Polymarker Color Index, 
vsm_color (14H) 

Set Text Font, vst_font (15H) 

Set Text Color Index, vst_color (16H) 

Set Fill Interior Style, vsfjnterior (17H) 

Set Fill Style Index, vsf.style (18H) 

Set Fill Color Index, vsf.color (19H) 

Inquire Color Representation, 
vq_color (1AH) 

Inquire Cell Array, vq.celtarray (1BH) 

Input Locator - Request Mode, 
vrqjocator (1CH) 
Input Locator - Sample Mode, 
vsmjocator (ICH) 



X X X X X 

X XX 

X X X X X 

X X X X X 

X X X X X 

XXX X X 

X X X X X 

X X X X X 

X X X X X 

X X X X X 

X X X X X 

X X X X X 

X XXX X 

X XX 
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Table 2-1. Required VDI Functions (Cont'd) 



Function (Opcode) 



Screen Printer Plotter Metafile Camera 



Input Valuator - Request Mode, 
vrq.valuator (1DH) 
Input Valuator - Sample Mode, 
vsm.valator (1DH) 

Input Choice - Request Mode, 
vrq.choice (1EH) 
Input Choice - Sample Mode, 
vsm_choice (1EH) 

Input String - Request Mode, 
vrq_string (1FH) 
Input String - Sample Mode, 
vsm_string (1FH) 

Set Writing Mode, vswr.mode (20H) 

Set Input Mode, vsin_mode (21 H) 

Inquire Current Polyline Attributes. 
vqLattributes (23H) 

Inquire Current Polymarker Attributes, 
vqm_attributes (24H) 

Inquire Current Fill Area Attributes, 
vqf.attributes (25H) 

Inquire Current Graphic Text Attributes. 
vqt_attributes (26H) 

Set Graphic Text Alignment, 
vst_alignment (27H) 

Open Virtual Workstation, 
v_opnvwk (64H) 

Close Virtual Workstation. 
v_clsvwk (65H) 
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Required Functions 



Table 2-1. Required VDI Functions (Cont'd) 



Function (Opcode) 



Screen Printer Plotter Metafile Camera 



Extended Inquire, vq_extnd (66H) X 

Contour Fill, v.contourfill (67H) 

Set Fill Perimeter Visibility, 

vsf_perimeter (68H) X 

Get Pixel. v_get_pixel (69H) 

Set Graphic Text Special Effects, 
vst_effects, (6AH) X 

Set Character Ceil Height, Points Mode, 
vst_point (6BH) X 

Set Polyline End Styles, vsLends (6CH) X 

Copy Raster, Opaque, vro_cpyfm (6DH) X 

Transform Form, vr_trn_fm {6EH) X 

Set Mouse Form, vsc_form (6FH) X 

Set User-defined Fill Pattern, 

vsf_udpat (70H) X 

Set User-defined Line Style, 

vsLudsty (71 H) X 

Fill Rectangle, vr_recfl (72H) X 

Inquire Input Mode, vqin.mode (73H) X 

Inquire Text Extent, vqt.extent (74H) X 

Inquire Character Cell Width. 

vqt_width (75H) X 

Exchange Timer Interrupt Vector, 

vex_timv (76H) X 

Load Fonts, vstjoadjonts (77H) X 
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Table 2-1. Required VDi Functions (Cont'd) 

Function (Opcode) Screen Printer Plotter Metafile Camera 

Unload Fonts, vst_unload_fonts (78H) X X X X X 

Copy Raster, Transparent, 

vrt_cpvfm (79H) X 

Show Cursor, v_show_c |7AH) X 

Hide Cursor, v_hide_c (7BH) X 

Sample mouse button state (7CH) X 

Exchange Button Change Vector. 

ve)c.butv (7DH) X 

Exchange Mouse Movement Vector, 
vex_motv (7EH) X 

Exchange Cursor Change Vector, 

vex_curv (7FH) X 

Sample Keyboard State Information, 
vq_key_s (BOH) X 

Set Clipping Rectangle, vs.clip (81 H) X X X X X 

Inquire Font Name and Index, 

vqt_name (82H) XXX X 

Inquire Current Font Information, 

vqt_fontJnfo (83H) XXX X 

Inquire Justified Graphics Text, 

vqt_justified (84H) X 
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Function Parameters 

Calling routines pass arguments to the VDI functions in the form of 
input arrays. The VDI returns values from the functions in output 
arrays. All arrays are zero-based and all array elements are WORD 
integers. The following names are used to refer to the arrays in the 
descriptions of the VDI functions: 

• control — the control array 

• intin — the array of integer input parameters 

• ptsin — the array of input point coordinates 

• Intout — the array of integer output parameters 

• ptsout — the array of output point coordinates 

The format that the VDI functions use for parameters is shown below 
under "Input Parameters" and "Output Parameters." 

VDI function calls can be made from applications written in assembly 
language or a high-level language. C language bindings are provided 
with GEM VDI and are shown in the description of each function. 

Assembly language routines address VDI functions according to their 
opcodes and place the LONGWORD address of the five parameter 
arrays in a ten-word data structure called a Parameter Block (PB). 
Figure 2-1 shows the format of the PB. 
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Contents 






Address of the 

control array 

(control) 


4 


Address of the 

integer input array 

(intin) 


8 


Address of the 

input point coordinate array 

(ptsin) 


12 


Address of the 

integer output array 

(intout) 


16 


Address of the 

output point coordinate array 

(ptsout) 



Figure 2-1. Parameter Block Format 



Prior to a VDI function call, the assembly language application: 

• Loads the address of the PB and the VDI ID number in the 
appropriate registers 

• Invokes the processor-specific interrupt or TRAP 

See Appendix E, "Processor-Specific Data," for the registers and 
Interrupts to be used for your system. 
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Function Parameters 



In the C language bindings, WORD declares a 16-bit integer type; BYTE 
declares an 8-bit integer type. 

Input Parameters: 

control(O) Opcode number for the VDI function 

control(l) Number of vertices in the ptsin array 

Each vertex consists of an x,y coordinate pair, so the 
length of the ptsin array is twice the number of 
specified vertices. 

control(3) Length of integer array intin 

control(5) Subfunction identification number for a Generalized 
Drawing Primitive (GDP) or Escape 

controi(6) Device handle 

control(7-n) Function dependent information 

intin Array of integer input parameters 

ptsin Array of input point coordinates 

Refer to the Extended inquire function, vq.extnd 
(66H), in Section 8 for Information on how to 
determine the maximum size of the ptsin array. 

Because coordinates may be converted by the GDOS, the calling 
routine must ensure that control(l), the number of vertices, Is correctly 
set. If no x,y coordinates are being passed to the VDI by the calling 
routine, control(l) must be set to 0. In addition, control(3), the Input 
integer count, must always be s^t. The calling routine must set 
control(3) to if it is not passing integers to the VDI. 
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Output Parameters: 

control(2) Number of vertices in the ptsout array 

Each vertex consists of an x,y coordinate pair, so the 
length of the ptsout array is twice the number of 
specified vertices. 

control(4) Length of integer array intout 

control(6) Device handle 

control(7-n) Function dependent information 

intout Array of integer output point parameters 

ptsout Array of output point coordinate data 

The VDI always sets control(2), the output vertex count and control(4), 
the output integer count, correctly. If it is not passing bacl( 
information in ptsout and intout, the VDI sets control(2) and control(4) 
to 0. 

Running Applications Under the VDI 

To use the graphics features provided by the VDI, you must ensure 
that the following conditions are met: 

1. Your program must conform to the VDI calling conventions to 
access graphics primitives. This process involves making a call to 
the GDOS and using the interrupt for your operating system. 
Refer to Appendix E for the specific interrupts. 

The parameter list provides information to the VDI and returns 
information to the calling program. 

2. Adequate stacic space must be made available for VDI operations. 
This space includes a buffer area for transforming points passed 
to the VDI and some fixed overhead space. "Memory 
Requirements," below, describes how to determine the required 
stacic space. 
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3. When your program is executed, the required device drivers must 
be located in the current directory at the time the VDI was 
Invoked (typically /GEMSYS). The ASSIGN.SYS file must contain 
the names of your device drivers and a device ID number for each 
device driver; refer to "The Assignment File, ASSIGN.SYS" In 
Section 1. 

4. After successfully compiling or assembling and linking your 
program, you can run it like any other application, once the VDI Is 
active. You can enable VDI graphics with the GEMVDI command, 
described below. 

Enabling Graphics 

Special commands let you enable graphics functions from the 
command level of the operating system. Each command loads the 
GDOS and any drivers declared resident in the ASSIGN.SYS file. 
ASSIGN.SYS and the driver files must be located in the current 
directory. 

Note that any application to be invoked by a GEM command must be 
located in the search path. 

To load the VDI and start a non-GEM application that uses the VDI 
(like a test program or debugger), enter the following command: 

GEMVDI /FILENAME 



Enter the following command to load the VDI and start a GEM 
application: 

GEMVDI FILENAME 



To load the VDI and start the GEM Desktop., application, enter: 
GEMVDI 
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Memory Requirements 

To determine the amount of stack space required to run a given 
graphics application, make the following calculation: 

Open Workstation call = approximately 128 bytes 

All other calls = ptsin size -^128 bytes + the overhead 
requirements of the operating system 

ptsin is the array of input point coordinates passed to the device 
driver from the application program (two words for each point). 

The stack requirement is the larger of the two resulting values. This 
stack space must be available in the application program stack area. 
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Running Applications Under the VDI 



Sample C Language Graphics Program 

Figure 2-2 depicts the output of the sample C language graphics 
program contained in Listing 2-1, below. To load the VDI and start 
such a program use the 

GEMVDI /FILENAME 
command. 




Figure 2-2. Output from the Polyline Sample Program 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 

/* 

int 

int 

int 

int 

int 

/* 

int 

int 

int 

int 



Listing 2-1. Sample C Language Program, Polyline 

This program, sample. c, uses the VDI to draw */ 
a simple picture and then wait for a single */ 
key to be pressed before terminating. 



To compile sample. c: 
Icl sample 
lc2 sample -v 

To link sample. c: 

link tcs+sample+vdibind+vdi asm, sample, 
sample/map, , 

Note: Modify ASSIGN. SYS so that the screen 
driver is resident (Olr XXXXXXXX . SYS ) 

To run sample. c: 

gemvdi /sample. exe 



VDI Global Arrays 
contrl[ll] ; 
intin[80]; 
ptsin[256] 
intout[45] 
ptsout[12] 

Local Data Area 
work_in[ll]; 
work_out[57] ; 
handle; 
pxyarray[12] ; 



int max_length; 

int echo_mode; 

int echo_xy[2]; 

char string[l]; 



■/ 

/* control inputs 

/* max string length 

/* polygon fill points 

/* v_opnwk output 

/* Points out array 



*/ 
/* 
/* 
/* 
/* 



Input for v_opnwk 
Return from v_opnwk 
Returned handle 
Points for Poly Line 



*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 



*/ 
*/ 
*/ 
*/ 
*/ 



*/ 
*/ 
*/ 
*/ 



/* Maximum string length */ 
/* Mode for char echo */ 
/* String x,y */ 

/* String array */ 
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Sample C Language Graphics Program 



MAINO 
{ 



Listing 2-1. (Cont'd) 

/* Called by TCS binding */ 



int 



1? 



/* Loop variable 



/* Clear work_in array for the VDI 
for (i = 0; i < 11; i++) 



work_in[i] = 0; 
work_inCO] = 1; 
work_in[l] = 1; 
work_in[2] = 1; 
work in[10] = 0; 



/* 
/* 
/* 
/* 



Dev ID (01 = Screen) 
Line type (Solid) 
Line Color (Black) 
Use NDC coordinates 



v_opnwk(work_in, Schandle, work_out); 



pxyarrayCO] = 12000 

pxyarrayfl] = 12000 

pxyarray[2] = 12000 

pxyarray[3] = 20000 

pxyarray[4] = 14000 

pxyarray[5] = 24000 

pxyarray[6] = 16000 

pxyarray[7] = 20000 

pxyarray[8] = 16000 

pxyarray[9] = 12000 

pxyarrayilO] = 12000 

pxyarrayill] = 12000 



/* Draw the polyline 

v_pline( handle, 6, pxyarray); 



*/ 
*/ 



*/ 
*/ 
*/ 
*/ 



/* v_pline vertices */ 



/ 



2-19 



Sample C Language Graphics Program GEM VDI Reference Guide 

Listing 2-1. (Cont'd) 

/* Length of the input string */ 

max_length = sizeof (string) ; 

echo^mode =0; /* Do not echo */ 
echo_xy[0] = 12000; /* x,y coordinates */ 
echo_xy[l] = 12000; /* for string input */ 

vrq_string( handle, max_length, echo_mode, 
echo_xy, Ststring); 

v_c lswk( handle ) ; /* Close workstation */ 



End of Section 2 
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Control Functions 



The VDI control functions initialize and close the graphics workstation, 
set workstation defaults, load and unload fonts, and enable or disable 
rectangle clipping. 

Table 3-1 lists and briefly describes each of the VDI control functions. 



Table 3-1. VDI Control Functions 



Function 



Page Purpose 



v.opnwk (1H) 


3-2 


v.clswk (2H) 


3-12 


v.clrwk (3H) 


3-13 


v_updwk (4H) 


3-14 


v_opnvwk (64H) 


3-15 


v.clsvwk (65H) 


3-17 


vstjoadjonts (77H) 


3-18 


vst_unload_fonts (78H) 


3-19 


vs.clip (81H) 
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Open a workstation 
Close a workstation 
Clear a workstation screen 
Execute all pending commands 
Open a virtual workstation 
Close a virtual workstation 
Load fonts named in ASSIGN.SYS 
Remove device's external fonts 
Enable/disable rectangle clipping 



Workstation default attributes are listed in the description of vopnwk 
(1H). 
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V_OPNWK (1H) 

The Open Workstation function loads a graphics device driver and 
returns a device handle and information that describes the device's 
general characteristics, v.opnwk initializes the device's line, color, 
marker, text, and fill style attribute values as specified in the input 
arguments. See Section 5 for detailed information about attribute 
values. Workstation default values are listed below in Table 3-2. 
Table 3-3 lists the default color table index values. 

If the specified device cannot be opened, v.opnwk returns a device 
handle value of zero. If the specified device is a screen, v.opnwk 
clears it and sets it to graphics mode; you do not need to call v.clrwrk 
(3H). 

When vopnwk is called to open a metafile, it initializes the file's 
buffer, writes the metafile header to the buffer, and returns the 
standard workstation information as described under "Output 
Arguments," below. See Appendix B for a description of the metafile 
and its header. 

Use vq.extnd (66H) to obtain additional device-specific information. 
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V_OPNWK (1H) 


Table 3-2. 


Workstation Default Attribute Values 


Attribute 


Default Value 


VDI Function 


Character height 


Nominal character height 


vst_height (CH) 


Character baseline 
rotation 


degrees rotation 


vst_rotation (DH) 


Text alignment 


Left baseline 


vst.alignment (27H) 


Text effect 


Normal intensity 


vst^effects (6AH) 


Line width 


Nominal line width 


vsLwidth (10H) 


Marker height 


Nominal marker height 


vsm_height (13H) 


Polyline end style 


Squared 


vsLends (6CH) 


Writing mode 


Replace 


vswr^mode (20H) 


Input mode 


Request for all devices 


vsln_mode (21 H) 


Fill perimeter 
visibility 


Visible 


vsf_perimeter (68H) 


User-defined 
line style 


Solid 


vsLudsty (71H) 


User-defined 
fill pattern 


DRI Logo 


vsf.udpat (70H) 


Cursor 


Hidden 


v_show_c (7AH) 
and v_hide_c (7BH) 


Clipping 


Disabled 


vs.clip (81 H) 



Use the VDI functions referenced in Table 3-2 to change the attribute 
values. 
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Table 3-3. Default Color Table Index Values 



Index 



Color 






White Default in 


1 


Blacic screens a 


2 


Red 


3 


Green 


4 


Blue 


5 


Cyan 


6 


Yellow 


7 


Magenta 


8 


White 


9 


Black 


10 


Dark Red 


11 


Dark Green 


12 


Dark Blue 


13 


Dark Cyan 


14 


Dark Yellow 


15 


Dark Magenta 


16 - n 


Device Dependent 



ndices for monochrome 



Index is defined as the current background color. 

Note that devices with less than 16 colors use the first "n" index 
entries, where "n" is the number of available colors. 
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Input Arguments 

workjn[0] Device ID number, defined as follows: 



work_ln[11 
worl<Jn[2l 



work_in[3l 
workJn[4l 

workJn[5) 

workJn[6] 

workJn[7] 



01 - 10 
11-20 
21 - 30 
31 - 40 
41 - 50 
51 - 60 



Screen 

Plotter 

Printer 

Metafile 

Camera 

Tablet 



Line type value, see vsLtyP© (PH) in Section 5 for 
information on line types. 

Polyline color index value; See Table 3-3 on page 
3-4 for a list of the default color index values, 
vsl.color (11H) may also be used to set the the 
polyline color index (see Section 5, "Attribute 
Functions"). 

Note: The VDI defaults to color index 1 if the index 
values you specify in workJn[2], workJn[4L 
workJn[6l, and workJn[9] are out of range. 

Polymarker type, see vsm_type (12H) In Section 5 for 
information on setting the polymarker type. 

Polymarker color index — see Table 3-3 on page 
3-4. Use vsm_color (14H), described in Section 5, to 
set the polymarker color index. 

Text font, see vst.font (15H) in Section 5 and 
vqt_name (82H) in Section 8 for Information on face 
selection. 

Text color index — see Table 3-3. vst_color (16H), 
described in Section 5, should be used to set the text 
color index after the workstation has been opened. 

Fill interior style, see vsfjnterior (17H) and vsf_style 
(18H) in Section 5 for information on fill interior style 
selection. 
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workJn[8] Fill style index — based on the fill interior style. For 
the pattern style, an index of 1 maps to the lowest 
intensity pattern on the device; if the fill interior style 
is solid, any index value produces an opaque fill style. 

work_in[9] Fill color index — see Table 3-3. vsf_color (19H), 
described in Section 5, should be used to set the fill 
color index after the workstation has been opened. 

work_in[10] NDC to RC transformation flag: 

Map full NDC space to full RC space 

1 Reserved 

2 Use RC system 

Output Arguments 

Note: See Table 3-2, above, for the default values of the attributes 
not included in the input arguments. 

handle Device handle, used in all subsequent VDI calls to 

select this device 

work_out[0] Maximum addressable x-point on the display surface 
in raster coordinates 

work_out[1] Maximum addressable y-point on the display surface 
in raster raster coordinates 

work_out[2] Device Coordinate units flag: 

Device produces precisely scaled image 

1 Device does not produce a precisely scaled image 

work_out[3] Pixel width in microns 

work_out[4] Pixel height in microns 

work_out[5] Number of character heights; zero indicates 
continuous scaling 

work_out[6] Number of line types 
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work_out[7] Number of line widths; zero indicates continuous 
scaling 

worlc_out[8] Number of marlcer types 

worl<_out[9] Number of marlcer sizes; zero indicates continuous 
scaling 

work_out[10] Number of fonts; you must load a font before 
sending output to devices that return zero, see 
vstjoadjonts (77H) In this section 

work_out[ll] Number of patterns 

work_out[12] Number of hatch styles 

work_out[13] Number of predefined colors (2 for monochrome) 

work_out[14] Number of Generalized Drawing Primitives (GDPs) 

work_out[15] 
to 

work_out[24] Sequential list of supported GDPs according to 
primitive id numbers (-1 = end of list): 

1 Bar -- v.bar (B-1H) 

2 Arc ~ v_arc (B-2H) 

3 Pie slice — v_piesllce (B-3H) 

4 Circle — v_circle (B-4H) 

5 Ellipse -- v_ellipse (B-5H) 

6 Elliptical arc — v_ellarc (B-6H) 

7 Elliptical pie ~ v.elipie (B-7H) 

8 Rounded rectangle — v_rbox (B-8H) 

9 Filled rounded rectangle — v_rfbox (B-9H) 
10 Justified graphics text — vjustified (B-AH) 
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work_out[25l 

to 
work_out[34] Sequential list of GDP attributes: 

Polyline 

1 Polymarker 

2 Text 

3 Fill area 

4 None 

work_out[35] Set Color Representation, vs_color (EH), flag: 

Unavailable 

1 Available 

work_out[36] Text Rotation, vst_rotation (DH), flag: 

Unavailable 

1 Available 

work_out[37] Filled Area, vjlllarea (9H) flag: 

Unavailable 

1 Available 

work_out[38l Cell Array, v_cellarray (AH), flag: 

Unavailable 

1 Available 

work_out[39] Number of available colors; zero indicates continuous 
color scaling, two indicates monochrome 

work_out[40] Number of available locator devices: 

None 

1 Keyboard only 

2 Keyboard and another locator 
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V_OPNWK (1H) 



work_out[41] Number of available valuator devices 
work_out[42] Number of available choice devices 
work_out[43] Number of available string devices: 

None 

1 Keyboard 



work_out[44] Workstation device type: 

Output only 

1 Input only 

2 Input/output 

3 Reserved 

4 Metafile-output 



Minimum character 
coordinates 



width in x-axIs NDC/RC 



work_out[45l 
work_out[46l 
work_out[47] 
work_out[48] Maximum character height in y-axis coordinates 



Minimum character 
coordinates 

Maximum character 
coordinates 



height In y-axis NDC/RC 



width In X-axis NDC/RC 



Note that minimum and maximum character height 
values do not include the interline and intercharacter 
spacing. 
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work_out[49] Minimum line width in x-axis NDC/RC coordinates 

work_out[50] 

work_out[51] Maximum line width in x-axis NDC/RC coordinates 

work_out[52] 

work_out[53l Minimum marker width in x-axis NDC/RC coordinates 

work_out[54] Minimum marker height in device's y-axis NDC/RC 
coordinates 

work_out[55] Maximum marker width in x-axis NDC/RC coordinates 

work_out[56l Maximum marker height in y-axIs NDC/RC 
coordinates 
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Sample Call to C Language Binding 

WORD v_opnwk{); 

WORD work_ln[11], work_out[57], handle; 

v_opnwk(workJn, Sihandie, work_out); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 1 
control(l) = 
control|2) = 6 
controlO) = 11 
control(4) = 45 
control|5) = 
controKB) = handle 



int 
int 
int 
Int 
int 
int 
int 
int 



in(0) 


= work i 


ln(1) 


= work 1 


in|2) 


= work i 


in(3) 


= work i 


in(4) 


= work i 


in|5) 


= work i 


in|6) 


= work i 


•n(7) 


= work i 



nlOl 


intout(O) 


= work out(0] 


nlll 


intout(l) 


= work outHl 


n(2] 


intout(2) 


= work outl2l 


nl3l 


intoutO) 


= work out[3] 


nl4l 


intout(4) 


= work outl4] 


nl5l 


intout(5) 


= work outl5l 


n[6] 


intout(6) 


= work outlel 


nl7l 


intout(7) 


= work outl7l 



intin(IO) = work_inl10l 



intoutdO) = work_outl10l 



intout(44) = work_outl44l 
ptsout(O) = work_outl45l 

ptsout(ll) = work_out[56] 
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V_CLSWK (2H) 

This function closes the worlcstation previously opened with v.opnwk 
(1H). All access to the device whose handle is specified in v.clswk is 
denied following the call, v.clswk performs the following close events 
for the indicated device type: 

Screen Selects the alpha device 

Plotter Performs an update 

Printer Performs an update 

Metafile Writes an end-of-file marker to the buffer, flushes it, 

and closes the file 
Camera Performs an update 

Note: Use v.clsvwk (65H) to close all virtual workstations before 
calling v_clswk. 

Input Arguments 

handle Device handle returned from v.opnwk (1H) 

Sample Call to C Language Binding 

WORD v_clswk(); 
WORD handle; 

v_clswk(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 2 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
controKS) = 
control(6) = handle 
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V_CLRWK (3H) 

This function clears the worl<station by performing the following 
events for each device type: 

Screen v.clrwk clears the screen and sets it to the 

background color. The background color is defined 
as index zero in the color table (see Section 5). 

Plotter v_clrwk clears the buffer. 

Printer v_clrwk clears the buffer and issues a form feed. 

Use v_form_adv {5-14H) to issue a form feed without 
clearing the buffer (see Section 9). 

IVletafile v.clrwk writes a metafile item to the metafile buffer. 

Camera v.clrwk clears the device and sets it to the currently 

selected background color. 

Note: You do not need to call v_clrwk after calling v_opnwk (IH). 
v.opnwk clears the device after opening the workstation. 

Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_clrwk(); 

WORD handle; 

v_clrwk(handle); 
Parameter Block Binding 

Control Input Output 

controKO) = 3 
controKD = 
control(2) = 
control{3) = 
control(4) = 
control|5) = 
controKG) = handle 
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V_UPDWK (4H) 

The Update Workstation function immediately executes the graphics 
commands currently stored in the specified device's buffer. 

Note: You must use v_updwk to initiate printer output; however, 
v_updwk does not perform a form feed command. Use v_clrwk (3H) or 
v_form_adv (5-14H) to perform a form feed. v_from_adv is described 
In Section 9, "Escape Functions." 

If the specified device is a metafile, v.updwk writes a metafile item to 
the metafile buffer. 

Because they execute graphics commands upon request, v.updwk does 
not affect screens. 



Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_updwk(); 
WORD handle; 

v_updwk(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 4 
control(l) = 
control(2) = 
controlO) = 
control(4) = 04 
controKS) = 
control(6) = handle 
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V_OPNVWK (64H) 

Open Virtual Woricstation opens and Initializes multiple virtual screens 
on a single physical workstation. The physical workstation, whose 
device handle is specified in the v.opnvwk control array, must be a 
screen device previously opened with v_opnwk (1H). v_opnvwk returns 
a device handle for the virtual workstation in the control array. If the 
virtual workstation cannot be opened, v_opnvwk returns a device 
handle value of zero. 

v_opnvwk gives each virtual workstation access to to the entire 
screen. The VDI maintains each workstation's attributes separately. 
For example, each virtual workstation may have different 
transformation modes and clipping rectangles. 

v.opvwk input and output arguments are the same as those for 
v_opnwk (IH); v_opnwk is described on page 3-2. 

Note: The VDI has no mechanism to control input device contention 
between several virtual workstations. It is the application's 
responsibility to manage its use of the VDI input functions. 
Applications with multiple virtual workstations should not access input 
devices in sample mode. See Section 7, "Input Functions," for more 
information. 



Input Arguments 

handle Screen device handle returned from v_opnwk (IH), 

specified in control array — this is the root device 
handle 

See page 3-5 for the other input arguments. 
Output Arguments 
See page 3-6 
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Sample Call to C Language Binding 

WORD v_opnvwk(); 

WORD workJn[1lL work_out[57L handle; 

v_opnvwk(workJn, Sihandle, work_out); 



Parameter Block Binding 



Control 


Input 


Output 


control(O) = 100 


intin(O) = work in[0] 


intout(O) - work out(0] 


control(l) - 


Intin(l) = work in(1] 


intout(l) = work out(1] 


control(2) = 6 


lntin(2) = work in(2l 


intout(2) = work out[2] 


controlO) = 11 


intin(3) = work in[3] 


IntoutO) = work outl3l 


control|4) = 45 


intin(4) = work in(4l 


intout(4) = work out(4l 


controKS) = 


lntin(5) = work inlS] 


intout(5) = work out[5l 


control(6) = handle 


intin(6) - work in[6] 


intout(6) = work out[6] 




intin(7) = work ln(7l 


intout(7) = work out[7l 



intin(IO) = work inllO] 



ir»tout(10) = workout[10l 



intout(44) = work_outl44l 
ptsout(O) = work_out(45l 

ptsout(ll) = work_out(56] 

Important: Control(6) is both an Input and an output argument. 
v_opnvwk returns the device handle for the virtual workstation in 
control(6). 
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V_CLSVWK (65H) 

This function closes a virtual workstation previously opened with 
v.opnvwk (64H). The virtual workstation handle specified in the 
v.cisvwk call is recycled. 

Input Arguments 

handle Device handle returned from v.opnvwk (64H) 

Sample Call to C Language Binding 

WORD v_clsvwk(); 
WORD handle; 

v_clsvwk(handle); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 101 
controMI) = 
control(2) = 
controlO) = 
control(4) = 
controMS) = 
control(6) = handle 
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VST_LOAD_FONTS (77H) 

The ASSIGN.SYS file associates external fonts with a particular device 
driver. This function loads the driver's external fonts Into memory, 
making them available to the calling program, and returns the number 
of additional font identifiers. 

If the specified device's external fonts were previously loaded, or 
ASSIGN.SYS does not associate any font files with the driver, 
vstjoadjonts returns zero. 

Note: You do not need to call vstjoadjonts if the driver's default 
system fonts are sufficient. 

Input Arguments 

handle Device handle 

select Reserved, must be zero 

Output Arguments 

additional Number of additional font identifiers 

Sample Call to C Language Bindin g 

WORD vstJoadJontsO; 
WORD additional, handle, select- 
additional = vstJoadJonts(handle, select); 

Parameter Block Binding 

Control Input Output 

control(O) = 119 intin(O) == select intout(O) = additional 

controMD = 

control(2) = 

controlO) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 
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VST_UNLOAD^FONTS (78H) 

This function dissociates the external fonts previously loaded by 
vst_load_fonts from the specified device. If possible, vst.unloadjonts 
frees up the memory occupied by the driver's external fonts. 

When the external fonts are shared by virtual workstations with the 
same root device handle, they are not unloaded from memory until 
one of the following conditions is met: 

• all workstations that share the fonts are closed, see v.clsvwk 
(65H) 

• this call has been made for all workstations that share the font 
The driver's default system fonts remain loaded and available. 

Input Arguments 

handle Device handle 

select Reserved for future use 

Sample Call to C Language Binding 

WORD vst_unload_fonts(); 
WORD handle, select; 

v_unload_fonts(handle, select); 

Parameter Block Binding 

Control Input Output 

control(O) = 120 intin(O) = select 

controlH) = 

contro!(2) = 

control|3) = 1 

control|4) = 

controHB) = 

control(6) = handle 
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VS.CLIP (81 H) 

vs.clip enables or disables the clipping of all output primitives by the 
VDI. Clipping refers to confining output to a rectangle defined within 
the device's display surface. Input arguments pxarray[0] to pxarray[3] 
specify the clipping rectangle's coordinates according to the current 
coordinate system (NDC or RC units). vq_extnd (66H), described in 
Section 8, indicates if clipping is currently enabled on the device 
(work_out[19]) and returns the coordinates of clipping rectangle in 
work_outl45l to work_out[48]. 

By default, clipping is disabled when the workstation is opened. 

If the specified device is a metafile, v.clip writes a metafile item to the 
metafile buffer. 

Input Arguments 

handle Device handle 

clip.flag Clipping flag: 

Disable clipping 

1 Enable clipping 

pxyarray[0] x-coordinate of corner of clipping rectangle 

pxyarray[1] y-coordinate of corner of clipping rectangle 

pxyarray[2] x-coordinate of corner diagonal to pxarray[0] 

pxyarray[3] y-coordinate of corner diagonal to pxarray[1] 

Sample Gail to Language Binding 

WORD vs.clipO; 

WORD handle, cllpjiag, pxyarray[4l; 

vs_clip(handle, clipjlag, pxyarray); 
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Parameter Block Binding 

Control Input Output 

intin(O) = cllp_flag 

ptsln(O) = pxarraylO] 
ptsin(l) = pxarrayMl 
ptsin(2) = pxarrayU] 
ptsinO) = pxarrayOI 
control(6) = handle 



End of Section 3 



control(O) = 


129 


controt(l) = 


2 


control|2) = 





controlO) = 


1 


control(4) = 





controKS) = 
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Output Functions 



The VDI output functions produce graphics primitives such as 
polylines, circles, and rounded rectangles. 

Table 4-1 lists and briefly describes the output functions. Output 
functions use the current line, marker, fill area, or text attributes. 
These attributes, the output functions that use them, and the attribute 
functions that control them are listed in Tables 4-2 through 4-5. 

Table 4-1. VDI Output Functions 



Function 



Page Purpose 



v_pline (6H) 4-4 

v_pmarker (7H) 4-6 

v_gtext (8H) 4-8 

vjillarea (9H) 4-10 

v.cellarray (AH)* 4-12 

v_bar(B-1H) 4-16 

v_arc (B-2H) 4-17 

v_pieslice (B-3H) 4-19 

v.circle (B-4H) 4-21 

v.ellipse (B-5H) 4-22 

v_ellarc (B-6H) 4-23 

v.ellpie {B-7H) 4-24 

v.rbox (B-8H) 4-25 

v.rfbox (B-QH) 4-26 

vjustifled (B-AH) 4-27 

v.contourfill (67H)* 4-29 

vr.recfl {72H) 4-30 



Draw a line between specified points 

Draw markers at specified points 

Write a text string 

Fill a polygon specified by points 

Draw a cell array 

Draw a filled rectangle 

Draw a circular arc 

Draw a filled circular arc 

Draw a filled circle 

Draw a filled ellipse 

Draw an elliptical arc 

Draw a filled elliptical arc 

Draw a rounded rectangle 

Draw a filled, rounded rectangle 

Display justified text 

Seed fill a specified area 

Fill a specified rectangle without perimeter 



These functions are either not required and may not be available on 
all devices, or contain unrequired options; see "Required Functions" In 
Section 2. 
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Table 4-2. Output Functions and Line Attributes 



Output Functions That Use Line Attributes 



v_pline (6H) v_arc (B-2H) v.ellarc (B-6H) v_rbox (B-8H) 



Line Attributes: 

Line type 
Line width 
Line coior 
Line end style 



Attribute Functions: 

vsLtype (FH) 
vsLwidth (lOH) 
vsLcolor (11H) 
vsLends (6CH) 



Table 4-3. Marker Attributes Used by v_pmarker 



Marker Attributes 



Attribute Functions 



IVIarker type 
Marker height 
Marker color 



vsmjype (12H) 
vsm.height (13H) 
vsmicolor (14H) 



Note: The attribute functions are described in Section 5. 



4-2 



GEM VDI Reference Guide 4.0 



Table 4-4. Output Functions and Fill Area Attributes 



Output Functions That Use Fill Area Attributes 



vjillarea (9H) v_bar (B-1H) v_pieslice (B-3H) 

v.circle (B-4H) v.eilipse (B-5H) v.eilpie (B-7H) 

v.rfboK (B-9H) v.contourflll (67H) vr.recfl (72H)* 

Fill Area Attributes: Attribute Functions: 



Fill Interior style vsfjnterlor (17H) 

Fill style Index vsf_style (18H) 

Fill area color vsf_color (19H) 

Fill perimeter vsf_perimeter (68H) 

Vr.recfl always operates with the fill perimeter disabled. 

Table 4-5. Output Functions and Text Attributes 

Output Functions That Use Text Attributes 

v_9text (8H) vjustlfled (B-AH) 

Text Attributes: Attribute Functions: 



Character height vst.helght (CH) 

Baseline vector vst_rotatlon (DH) 

Text face vstjont (15H) 

Text color vst_color (16H) 

Text alignment vst_alignment {27H) 

Text effect vst.effects (6AH) 

Cell height, points vst_point (6BH) 



Note: The output functions operate according to the current writing 
mode as controlled by vswr_mode (20H). vswr_mode is described in 
Section 5. vs.cilp (81 H), described in Section 3, defines the area on 
the screen where an output function is allowed to draw. 
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V.PLINE (6H) 

This function displays a polyline on the graphics device. The line's 
starting point is specified in the first coordinate pair (xy[0] and xy[1]). 
v_pline draws the line between subsequent points as specified in the 
remaining input arguments according to the current coordinate system 
(NDC or RC units). 

v_pline displays a zero length line (degenerate case) as a point and 
does not display a single coordinate pair. Use vq.extnd (66H), 
described in Section 8, "inquire Functions," to obtain the maximum 
number of input vertices for the specified device. 

vj)line produces lines according to the line attributes listed in Table 
4-2, above, and the current writing mode. You can use vql.attributes 
(23H) to obtain the current settings of the line attributes. 



Input Arguments 
handle 
count 
xy[0] 
xy[l] 
xy[2] 
xy[3l 



Device handle 

Number of input vertices (n) 
x-coordinate of first point 
y-coordinate of first point 
x-coordinate of second point 
y-coordinate of second point 



xy[2*count-2] x-coordinate of last point 
xy[2*count-1] y-coordinate of last point 
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Sample Call to C Language Binding 

WORD v_pllne{); 

WORD handle, count. xyU * count]; 

v_pline(handle, count, xy); 
Parameter Block Binding 

Control Input 

control(O) = 6 ptsin(O) = xylOl 

control(l) = count ptsin(l) = xytH 

control(2) = ptsin(2) = xy[2] 

controlO) = ptsln(3) = myI3) 
control|4) = 
control(5) = 

control(6) = handle ptsin(2*count-2) = xv[2*count-2l 

ptsin(2*count-l) = xyl2*count-ll 
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V.PMARKER (7H) 

This function draws mariners at the points specified in the input 
argument coordinates (in NDC or RC units). v_pmarker produces 
markers according to the attributes listed in Table 4-3 and the current 
writing mode, vqm.attributes (24H), described in Section 8, returns the 
current settings of these attributes. 

Use vq.extnd (66H), to obtain the maximum number of polymarker 
vertices for the specified device. 



Input Arguments 

handle 

count 

xy[0] 

xy[11 

xy[2l 

xy[3] 



Device handle 

Number of input vertices (n) 
x-coordinate of first marker 
y-coordlnate of first marker 
x-coordinate of second marker 
y-coordinate of second marker 



xy[2*count-2] x-coordinate" of last marker 
xy[2*count-l] y-coordinate of last marker 

Sample Call to C Language Binding 

WORD v.markerO; 

WORD handle, count, xy[2 * count] 

v_pmarker(handle, count, xy); 
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Parameter Block Binding 

Control Input 

controKO) = 7 ptsin(O) = xylOl 

control(l) = count ptsin(l) = xy[1] 

controi{2) = ptsin(2) = xyizj 

controlO) = ptsin(3) = xyisl 
control(4) = 
controKS) = 

controt(6) = handle ptsin(2'*count-2) = xvl2*count-2| 

ptsin(2*count-1) = xyl2*count-1) 
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V.GTEXT (8H) 

v_gtext writes a text string to the display surface. The (x,y) position 
specified by the calling routine Is the alignment point of the text string 
in units of the current coordinate system (NDC or RC). The 
vst.allgnment function establishes the relationship between the string's 
starting point and the specified x,y position (see in Section 5). See 
Table 4-5, above, for other text attributes that affect the operation of 
v_gtext. 

Note that vqt.attributes (26H) returns the current text attribute settings 
(see Section 8, "Inquire Functions"). 

For the C language binding, the string input argument is byte-oriented 
and must be null-terminated. For the Parameter Block (assembly 
language) binding, the string Is word-oriented. Any unsupported 
character Is mapped to a question mark (?), the symbol for an 
undefined character. work_out[15l of vq_extnd (66H) returns the 
maximum number of characters (size of intin array) allowed in the text 
string, vq.extnd is described In Section 8. 

Be sure that the specified device has a font loaded before outputting 
text. Printers and some other devices may not have a system font 
available; if v_opnwk (1H) returned zero In work_out[10] when the 
device was opened, call vstjoadjonts (77H) before v_gtext. v_opnwk 
and vstjoad.fonts are described in Section 3, "Control Functions." 

Input Arguments 

handle Device handle 

X x-coordlnate of text string's alignment point 

y y-coordinate of text string's alignment point 

string ASCII character string 
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Sample Call to C Language Binding 

WORD v_gtext(); 
WORD handle, x, y; 
BYTE *string; 

v_gtext{handle, x, y, string); 
Parameter Block Binding 

Control Input Output 

control(O) = 8 intin = string (in 16-bit 

control(l) = 1 characters) 

control(2) =0 

controlO) = number of ptsin(O) = x\ 

chars in string 

control(4) = ptsin(l) = y 

control(5) = 

control(6) = handle 
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V_FILLAREA (9H) 

The v_fillarea function fills the polygon defined by the input argument 
coordinates (in NDC or RC units) according to the fill area attributes 
listed in Table 4-4 and the writing mode. Use vqf_attributes {25H) to 
obtain the current settings of the attributes that affect the operation of 
this function (see Section 8, "Inquire Functions"). 

When the fill perimeter attribute is enabled (visibile), v.fillarea outlines 
the polygon with a solid line of the current fill area color. If the 
specified device does not have fill area capability, the polygon is 
outlined with the current fill area color. 

A polygon with zero area (degenerate case) is displayed as a dot only 
when the fill perimeter attribute is enabled. If the fill perimeter 
attribute is disabled, a dot is not displayed for the degenerate case. 

v.fillarea does not display a polygon with only one vertex. The device 
driver ensures that the fill area is closed by connecting the first point 
to the last point. 

work_out[14] of vq_extnd (66H) returns the maximum number of input 
vertices you may use to define a polygon. 



Input Arguments 
handle 
count 
xy[Ol 
xyll] 
xy[2l 
xyl3] 



Device handle 

Number of input vertices (n) 
x-coordinate of first point 
y-coordinate of first point 
x-coordinate of second point 
y-coordinate of second point 



xy[2*count-2] x-coordinate of last point 
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xy[2*count-1] ycoordinate of last point 

Sample Call to C Lang ua ge Bindin g 

WORD vJillareaO; 

WORD handle, count, xy[2 * count]; 

v_fillarea(handle, count, xy); 
Parameter Block Binding 

Control Input 

control(O) = 9 ptsin(O) = xytO) 

control(l) = count ptsin(l) = xyll] 

control(2) = ptsin(2) = xyizj 

controlO) = ptsm{3) = xy(3l 
control(4) = 
controllS) = 

control(6) = handle ptsin(2*count-2) = xYl2*count-2j 

ptsin(2*count-l) = xy[2*count-11 
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V_CELLARRAY (AH) 

This function draws the rectangular array defined by the pxyarray Input 
coordinates (in NDC or RC units) and divides it into color cells of equal 
size and shape based on the length and number of each row In the 
color Index array. The color Index array determines the color for each 
cell; It is composed of indices selected from the color table (see 
Section 5). 

Each cell of the rectangle is mapped to pixels on the display surface. 
A pixel takes the color of the cell that covers its center. 

If the specified device does not support ceil arrays, the rectangle is 
outlined with a solid line in the current line color and line width. 

Use the vq.cellarray (IBH) function to obtain information about a 
previously defined cell array — see Section 8, "Inquire Functions." 

Note: v.cellarray may not be supported by ail devices drivers. 
work_out[38l of v_opnwk (IH) returns zero if the device does not 
provide this function. 

Input Arguments 

handle Device handle 

rowjength Length of each row in color index array (size as 
declared in a high-level language) 

el.used Number of elements used in each row (number of 

columns) of color Index array 

num_rows Number of rows In color Index array 

wrt_mode Pixel operation (write mode) to be performed: 

1 Replace 

2 Transparent 

3 XOR 

4 Reverse transparent 

See vswr.mode (20H) in Section 5 for a description 
of each mode. 
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V_CELLARRAY (AH) 



colarrayLO] Color index array, stored by row 

colarray[n] Last row of color index 

The size of the array equals (num.rows * eLused). 

pxyarray[0] x-coordinate of rectangle's lower left corner 

pxyarray[1] y-coordlnate of rectangle's lower left corner 

pxyarray[2l x-coordinate of rectangle's upper right corner 

pxyarray[3] y-coordinate of rectangle's upper right corner 

Sample Call to C Language Bindin g 

WORD vcellarrayO; 

WORD handle, pxyarray[4], rowjength, elused, numrows, wrtmode, 
colarray[num_rows*el_used]; 

v_cellarray(handle, pxyarray, rowjength, elused, numrows, 
wrt mode, colarray) 



Parameter Block Binding 

Control Input 



Output 



controllO) = 10 

control(l) = 2 

control(2) = 

controlO) = n 

control(4) = 

control(5) = 

control(6) = handle 

control!?) = rowjength 

control(8) = eLused 

control(9) = num_rows 

control! 10) = wrt_mode 



intin!0) = cotarraylO] 



intin!n) = colarrayln] 

ptsiniO) = pxyarraylOj 

ptsin!1) = pxyarrayhj 

ptsin!2) = pxyarray(2] 

ptsin!3) = pxyarrayl3l 
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Generalized Drawing Primitives 

The Generalized Drawing Primitives (GDPs) produce special graphics 
elements such as arcs, circles, and ellipses. 

All GDPs share the same opcode; however, input and output 
arguments and the arrays are primitive-dependent. The calling routine 
specifies the function to be performed according to the primitive's ID 
number, which is contained in control(5). The primitive ID numbers are 
listed below: 

1 Bar — v_bar 

2 Arc — v_arc 

3 Pie slice — v_pleslice 

4 Circle — v_clrcle 

5 Ellipse — v_ellipse 

6 Elliptical arc — v_ellarc 

7 Elliptical pie — v_ellpie 

8 Rounded rectangle — v_rbox 

9 Filled rounded rectangle — v_rfbox 
10 Justified graphics text — vjustified 
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GPP Angle Specifications 



All GDP Input angle specifications must be in tenths of degrees. 
degrees is 90 degrees to the right of vertical. As shown in Figure 4-1, 
values increase in the counterclockwise direction. Arcs are drawn 
counterclockwise. 

All radius arguments, except for v_elllpse (B-5H) and v_ellarc (B-6H), 
specify an extent (distance) in x-axis units. The v.ellipse and v.ellarc 
functions use both x and y axis units. 



90 



180 



270 



Figure 4-1. GDP Angle Specification 



Note that all GDP coordinates are specified in units of the current 
coordinate system (NDC or RC). 

Descriptions of the individual GDP functions follow. 
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V_BAR (B-1H) 

This function draws a rectangle using the current writing mode and fill 
area attributes. These attributes are listed in Table 4-4, above; use 
the vqf_attributes function (25H) to obtain their current settings. 

Input Arguments 

pxyarray[0] x-coordinate of corner of bar 

pxyarrayEl] y-coordinate of corner of bar 

pxyarray[2] x-coordinate of corner diagonal to pxyarray[0] 

pxyarray[3] y-coordinate of corner diagonal to pxyarray[1] 

Sample Call to C Language Bind ing 

WORD v_bar(); 

WORD handle, pxyarray[4]; 

v_bar(handle, pxyarray); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 11 

control(l) = 2 

control(2) = 

controlO) = 

control(4) = 

controMS) = 1 

control(6) = handle 



ptsin(O) = pxyarraylO] 
ptsin(l) = pxyarrayfl] 
ptsin(2) = pxyarray(2] 
ptsinO) = pxyarrayOl 
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V_ARC (B-2H) 

v_arc draws an arc using the .current writing mode and polyline 
attributes. These attributes are listed In Table 4-2, above; use 
vql.attributes (23H) to obtain their current settings. 

Arcs are defined for v.arc by the beginning and ending angles, center 
point (x- and y-coordinates), and the length of the radius as measured 
on the X axis. 



Input Arguments 

handle Device handle 

begang Beginning angle in tenths of degrees, (0-3600) 

endang Ending angle in tenths of degrees, (0-3600) 

X x-coordinate of arc's center point 

y y-coordinate of arc's center point 

radius Length of arc's radius in x-axis units 

Sample Call to C Language Binding 

WORD v_arc(); 

WORD handle, x, y, radius, begang, endang; 

v_arc(handle, x, y, radius, begang, endang); 



4-17 



VJVRC (B-2H) 



GEM VDi Reference Guide 



Parameter Biock Binding 

Control Input 



Output 



control(O) = 11 

control(l) = 4 

control(2) = 

ccntrolO) = 2 

control(4) = 

controKS) = 2 

control(6) = handle 



intin(O) = begang 
intin(l) = endang 



pts 
pts 
pts 
pts 
pts 
pts 
pts 
pts 



n(0) = X 
nil) = V 
n(2) = 
n(3) = 
n|4) = 
n(5) = 
n(6) = radius 
n|7) = 
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V_PIESLICE (B-3H) 

This function draws a pie slice using the current writing mode and fill 
area attributes. Table 4-4, above, lists the fill area attributes. Use the 
vqf_attributes function (25H) to obtain the current attribute settings. 

Specify the pie slice by its beginning and ending angles, center point 
(x- and y-coordinates), and the length of its radius, measured on the x 
axis. v_pieslice draws the pieslice counter-clockwise from the 
beginning angle to the end angle. 

Input Arguments 

handle Device handle 

begang Beginning angle in tenths of degrees, (0-3600) 

endang Ending angle in tenths of degrees, (0-3600) 

X x-coordinate of center point of pie slice 

y y-coordinate of center point of pie slice 

radius Length of radius of pie slice in x-axis units 

Sample Call to C Language Bindin g 

WORD v_pieslice(); 

WORD handle, x, y, radius, begang, endang; 

v_pieslice(handle, x, y, radius, begang, endang); 



4-19 



V.PIESLICE (B-3H) GEM VDI Reference Guide 

Parameter Block Binding 

Output 



Control 


Input 


control(O) = 11 


intin(O) = begang 


control(l) = 4 


intin(l) = endang 


control(2) = 




controlO) = 2 


ptsin(O) = X 


control(4) = 


ptsind) = y 


controKS) = 3 


ptsin(2) = 


control(6) = handle 


ptsin(3) = 




ptsin(4) = 




ptsinIS) = 




ptsin(6) = radius 




ptsln|7) = 
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V_CIRCLE (B-4H) 

This function draws a circle using the current writing mode and fill 
area attributes. These attributes are listed in Table 4-4, above; use 
vqf_attributes (25H) to obtain their current settings. 

Specify the circle by the x- and y-coordinates of its center point and 
the length of its radius as measured on the x-axis. 

Input Arguments 

handle Device handle 

X x-coordinate of circle's center point 

y y-coordinate of circle's center point 

radius Length circle's of radius in x-axis units 

Sample Call to C Language Binding 

WORD v_circle(); 

WORD handle, x, y, radius; 

v_circle(handle, x, y, radius); 
Parameter Block Binding 

Control Input Output 

control(O) = 11 ptsin(O) = x 

controilD = 3 ptsln(l) = y 

control(2) = ptsin(2) = 

controlO) = ptsin(3) = 

control(4) = ptsin(4) = radius 

control(5) = 4 ptsin|5) = 
control(6) = handle 
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V.ELLIPSE (B-5H) 

This function draws an eillpse using the writing nnode and fill area 
attributes. These attributes are listed in Table 4-4. vqf.attributes 
(25H) returns the current settings of the attributes that affect the 
operation of v.ellipse. 

An ellipse is defined for v.ellipse by the x- and y-coordinates of the 
ellipse's center point, the x-axis radius, and the y-axis radius. 

Input Arguments 

handle Device handle 

x x-coordinate of ellipse's center point 

y y-coordinate of ellipse's center point 

xradius Radius in x-axis units 

yradius Radius in y-axis units 

Sample Caii to C Language Binding 

WORD v.ellipseO; 

WORD handle, x, y, xradius, yradius; 

v_ellipse(handle, x, y, xradius, yradius); 
Parameter Block Binding 

Control Input Output 

control(O) = 11 ptsin(O) = x 

control(l) = 2 ptsin(l) = y 

control(2) = ptsin(2) = xradius 

controlO) = ptsin(3) = yradius 

control(4) = 
control(5) = 5 
control(6) = handle 
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V^ELLARC (B-6H) 

This function draws an elliptical arc. It uses the writing mode and line 
attributes. The line attributes are listed in Table 4-2; use vql.attributes 
(23H) to obtain their current settings. 

Define an elliptical arc for v.ellarc by specifying its beginning and 
ending angles, the x- and y-coordlnates of its center point, its x-axis 
radius, and its y-axis radius. 

Input Arguments 

handle Device handle 

begang Beginning angle in tenths of degrees, (0-3600) 

endang Ending angle in tenths of degrees, (0-3600) 

X x-coordinate of arc's center point 

y y-coordinate of arc's center point 

xradius Radius in x-axis units 

yradlus Radius in y-axis units 
Sample Call to C Language Bindin g 

WORD v_ellarc(); 

WORD handle, x, y, xradius, yradlus, begang, endang; 

v_ellarc(handle, x, y, xradius, yradius, begang, endang); 
Parameter Block Binding 

Control Input Output 

control(O) = 11 intin(O) = begang 

control(l) = 2 Intin(l) = endang 
control(2) = 

controlO) = 2 ptsln(O) = x 

control(4) = ptsin(l) = y 

controKS) = 6 ptsin(2) = xradius 

contro!(6) = handle ptsin(3) = yradius 
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V_ELLPIE (B-7H) 

This function draws an elliptical pie segment using the writing mode 
and fill area attributes. Table 4-4 lists the fill attributes; use 
vqf_attributes (25H) to obtain their current settings. 

Define the elliptical pie segment for v.ellpie by specifying its 
beginning and ending angles, the x- and y-coordinates of its center 
point, its X-axis radius, and its y-axis radius. 

input Arguments 

handle Device handle 

begang Beginning angle in tenths of degrees, (0-3600) 

endang Ending angle in tenths of degrees, (0-3600) 

X x-coordinate of arc's center point 

y y-coordinate of arc's center point 

xradius Radius in x-axis units 

yradius Radius In y-axis units 
Sample Call to C Language Binding 

WORD v_ellpie(); 

WORD handle, x, y, xradius, yradius, begang, endang; 

v_ellpie(handle, x, y, xradius, yradius, begang, endang); 
Parameter Blocl< Binding 

Control Input Output 

control(O) = 11 intin(O) = begang 

control(l) = 2 Intln(l) = endang 

controlU) = 

controlO) = 2 ptsin(O) = x 

control{4) = ptsin(l) = V 

controKS) = 7 ptsin(2) = xradius 

control(6) = handle ptsln(3) = yradius 
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V^RBOX (B-8H) 

v_rbox draws a rectangle with rounded corners. This functions uses 
the current writing mode and line attributes. See Table 4-2, above. 
vqLattrlbutes (23H) returns the current settings of the attributes that 
affect v_rbox. 

Define the rectangle by specifying coordinates (NDC or RC units) for 
two of Its corners. 



Input Arguments 

Handle device handle 

xyarray[0] x-coordinate of rectangle corner 

xyarray[1] y-coordlnate of rectangle corner 

xyarray[2] x-coordinate of corner diagonal to xyarray[Ol 

xyarray[3] y-coordinate of corner diagonal to xyarray[11 

Sample Call to C Lang u age Binding 

WORD v_rbox(); 

WORD handle, xyarray[4]; 

v_rbox{handle, xyarray); 
Parameter Block Binding 

Control Input Output 

control(O) = 11 ptsin(O) = xyarraylOl 

controi(l) = 2 ptsin(l) = xyarrayll] 

control(2) =0 ptsin{2) = xyarrayl2i 

controlO) = ptsin(3) = xyarrayO] 

control(4) = 

controKS) = 8 

control(6) = handle 
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V.RFBOX (B-9H) 

This function draws a filled rectangle with rounded corners. v_rfbox 
uses the current writing mode and fill area attributes. Table 4-2, 
above, lists the fill area attributes; use vqf.attributes (25H) to obtain 
their current settings. 

Define the rounded rectangle to be filled by specifying the coordinates 
(NDC or RC units) for two of its corners. 

Input Arguments 

Handle device handle 

xyarray[0] x-coordinate of rectangle corner 

xyarray[1] y-coordinate of rectangle corner 

xyarray[2] x-coordinate of corner diagonal to xyarray[0] 

xyarray[3] y-coordinate of corner diagonal to xyarray[l] 

Sample Call to C Language Binding 

WORD v_rfbox(); 

WORD handle, xyarray[4]; 

v_rfbox(handle, xyarray); 



Parameter Block Binding 

Control Input 



Output 



controi(O) = 11 

control(l) = 2 

control(2) = 

controlO) = 

control(4) = 

controKS) = 9 

control(6) = handle 



ptsin(O) = xyarraylO] 
ptsin(l) - xvarrayll] 
ptsin(2) = xvarray[2] 
ptsin(3) = xyarrayOl 
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V_JUSTIFIED (B-AH) 

This function writes and attempts to justify both the left and right 
margins of a text string. The text string is justified according to the 
alignment points, passed as input arguments x and y, and the 
requested string length, x, y, and length are specified in units of the 
current coordinate system (NDC or RC). 

vjustified uses the current writing mode and text alignment attributes; 
see Table 4-5. Use vqt_attributes (26H) to obtain the current settings 
of the attributes that affect the operation of vjustified. 

You can specify whether or not vjustified is to modify the inter-word 
and/or inter-character spacing to match the requested length of the 
text string with the word_space and char_space arguments. 

For the C language binding, the string input argument is byte-oriented 
and must be null-terminated. For the Parameter Block (assembly 
language) binding, the string Is word-oriented. Any unsupported 
character is mapped to a question mark (?), the symbol for an 
undefined character. vq_extnd (66H), described in Section 8, returns 
the maximum number of characters (size of intin array) allowed in the 
text string. 

The vqtjustified function (84H), also described in Section 8, returns 
the X- and y-axis offsets for each character in a text string given the 
same input arguments as vjustified. 

Be sure that the specified device has a font loaded before outputting 
text. Printers and some other devices may not have a system font 
available; if v_opnwk (1H) returned zero in work.outllO] when the 
device was opened, call vstjoadjonts (77H) before vjustified. 
v_opnwk and vstjoadjonts are described in Section 3, "Control 
Functions." 



4-27 



VJUSTIFIED (B-AH) 



GEM VDI Reference Guide 



input Arguments 

word.space Word spacing flag: 

zero Do not modify inter-word spacing 

nonzero Modify inter-word spacing 

cliar_space Character spacing flag: 

zero Do not modify Inter-character spacing 

nonzero Modify Inter-character spacing 

string ASCII character string 

X x-coordlnate of the text alignment point 

y y-coordinate of the text alignment point 

length Requested length of the string, in x-axis units 



Sample Gail to C Language Bindin g 

WORD vJustifiedQ; 

WORD handle, x, y, length, wordspace, WORD char^space; 

BYTE string(n); 

vjustified(handle, x, y, string, length, wordspace, charspace); 



Parameter Bioci< Binding 

Control Input 



Output 



control(O) = 11 
controKD = 2 
control(2) = 
controlO) = 2+n 
control(4) = 
controKS) = 10 
control(6) = handle 



intin(O) = word_space 
intin(l) - char.space 
intin(n+2) - string(n) 



ptsln(O) = X 

ptsin(l) = V 

ptsln(2) = length 

ptsinO) = 

Note: "n" is used here to represent the number of characters in the 
string. 
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V_CONTOURFILL (67H) 

This function is often referred to as "seed" or "flood" fill, it fills an 
area using the current fill area attributes until it reaches either the 
edge of the screen or a specified color. Table 4-4 lists the fill area 
attributes; use vqf.attributes (25H) to obtain their current settings. 

The center point of the area to be filled is specified in the x and y 
arguments using units of the current coordinate system. The color 
that defines the contour to be filled by v.contourfill is specified as a 
fill area color index value. If this value is negative, v.contourfill 
searches for any color other than the color of the seed point. 

Note: This function may not be supported by all device drivers. 
Check worlc_out[7] of vq_extnd (66H) to determine If the device has 
seed fill capability. 

Input Arguments 

index Color index that defines the contour 

X x-coordinate of starting point 

y y-coordinate of starting point 

Sample Call to C Language Binding 

WORD v_contourfill(); 
WORD handle, x, y, index; 

v_contourfill(handle, x, y, index) 
Parameter Block Binding 

Control Input Output 

control(O) » 103 intin(O) = index 

controMD = 1 

control(2) = ptsin(O) = x 

controlO) = 1 ptsin(l) = y 

control(4) = 

control(5) = 

controt(6) = handle 
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VR.RECFL (72H) 

vr.recfl fills a rectangle whose area is defined by the pxyarray 
arguments in units of the current coordinate system (NDC or RC) 
according to the fill area attributes. This function is similar to v_bar 
(B-1H) except that the fill perimeter attribute is not used. Regardless 
of its current setting, vr.recfl operates with the fill perimeter attribute 
disabled (invisibile). 

The fill area attributes are listed in Table 4-4, above; vqf.attributes 
(25H) returns their current settings. 

Input Arguments 

pxyarrayEO] x-coordinate of corner of rectangle 
pxyarray[1] y-coordinate of corner of rectangle 
pxyarray[2] x-coordinate of corner diagonal to pxyarray[0] 
pxyarray[3] y-coordinate of corner diagonal to pxyarray[11 
Sample Call to C Language Bindin g 

WORD vr_recfl(); 

WORD handle, pxyarray[4l; 

v_recfl(handle, pxyarray); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 114 
control(l) = 2 
control(2) = 
controlO) = 
control(4) = 
controKS) = 



ptsin(O) = pxyarraylO] 
ptsin(l) = pxyarrayll] 
ptsin(2) - pxyarray[2] 
ptsin(3) = pxyarray[3] 



control(6) = handle 



End of Section 4 
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The VDI attribute functions control how output Items are imposed over 
existing pixel values (the writing mode) and determine the 
characteristics of the output functions. The output function 
characteristics determined by the attribute functions Include color, line 
type, marker type, fill pattern and style, and character height. 

Note that the function descriptions in this section are organized 
according to the attributes they control, rather than opcode. 

Table 5-1 lists each of the VDI attribute functions. 
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Table 5-1. VDI Attribute Functions 



Function 



Page Purpose 



vst.helght (CH) 5-19 

vst_rotation (DH) 5-23 

vs.color (EH) 5-6 

vsl.type (FH) 5-8 

vsLwIdth (lOH) 5-11 

vsLcolor (11H) 5-12 

vsm_type (12H) 5-15 

vsm.height (13H) 5-17 

vsm_color (14H) 5-18 

vstjont (15H) 5-25 

vst.color (16H) 5-27 

vsfjnterior (17H) 5-33 

vsf.style (18H) 5-35 

vsf.color (19H) 5-38 

vswr_mode (20H) 5-3 

vst.alignment (27H) 5-31 

vsf_perlmeter (68H) 5-39 

vst.effects (6AH) 5-28 

vst_point (6BH) 5-21 

vsLends (6CH) 5-13 

vsf.udpat (70H) 5-40 

vsl.udsty (71H) 5-10 



Set character height, abolute mode 

Set the character baseline vector 

Determine color representation 

Set the line type 

Set the line width 

Set the line color index 

Set the polymarlcer type 

Set polymaker height 

Set the polymarlcer color index 

Select a character font 

Set the text color index 

Set the fill interior style 

Set the fill style index 

Set the fill color index 

Select the writing mode 

Set text alignment 

Determine fill area perimeter visibility 

Set special effects for text 

Set character height points mode 

Set line end styles 

Set a user-defined fill pattern 

Set a user-defined line style 
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VSWR.MODE (20H) 

This function selects the writing mode. The writing mode affects the 
way new pixels for subsequent drawing operations are placed on the 
display. The calling routine specifies the operation to be performed 
between the color indices of the current pixel (source) and the existing 
pixel (destination) by selecting one of four writing modes. 

The writing modes are: replace, transparent, XOR, and reverse 
transparent. work_out[9l of vq_extnd (66H) returns the number of 
writing modes available on a particular device — see Section 8. Table 
5-2 defines the operands used in the Boolean expressions that 
describe the four writing modes. 



Table 5-2. Writing Mode Operands 

Operand Definition 

mask Line style or fill pattern 

fore Selected color after mapping from the VDI 

back Color after mapping from the VDI 

(white is default) 

old Current color value 

new Replacement color value 



Mode 1, Replace 

Replace mode is insensitive to the currently displayed image. Any 
information already displayed is replaced. This is the default writing 
mode when the workstation is opened. The Boolean expression for 
replace mode is: 

new = (fore AND mask) OR (back AND NOT mask) 
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Mode 2, Transparent 

Transparent mode affects only the pixels where the mask is 1. These 
are changed to the fore value. The Boolean expression for transparent 
mode is: 

new = (fore AND mask) OR (old AND NOT mask) 



Mode 3. XOR 

XOR mode reverses the bits representing the color. The Boolean 
expression for XOR mode is as follows: 

new = mask XOR old 



Mode 4, Reverse Transparent 

Reverse transparent mode affects only the pixels where the mask is 0, 
changing them to the fore value. The Boolean expression for this 
mode is: 

new = (old AND mask) OR (fore AND NOT mask) 



Input Arguments 

handle Device handle 



mode 



Writing mode: 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 

if the writing mode specified by the calling routine is 
not in the range of 1 - 4, vswr_mode selects replace 
mode, 1. 
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Output Arguments 

set.mode Selected writing mode 

Sample Call to C Language Binding 

WORD vswr_mode(); 

WORD set_mode, handle, mode; 

set_mode = vswr_mode(handle, mode); 
Parameter Block Binding 

Control Input Output 

control(O) = 32 intin(O) = mode Intout(O) - set_mode 

control(l) = 

control(2) = 

control|3) =1 

control(4) = 1 

control(5) = 

control(6) = handle 
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VS.COLOR (EH) 

Set Color Representation assigns a specified color index to units of 
RGB (Red, Green, Blue) intensity. The calling routine specifies the unit 
of intensity for each of the three colors in tenths of a percent (0 - 
1000). 

If the specified value of a color intensity Is less than 0, vs_color nnaps 
the value to 0; an intensity value of greater that 1000 is mapped to 
1000. 

On a monochrome device, the VDI maps any percentage of color to 
white. The background color is referenced as color index zero. The 
default color table index values are listed In Table 3-3 on page 3-4. 

The number of color indices is device dependent; work_out[13] of 
v_opnwk (1H) and v_opnvvyk (64H) returns the number of colors that 
can be defined. v_opnwk and v_opnvwk are described in Section 3, 
"Control Functions." 

Note: This function performs no operation if a color lookup table is 
not supported for the specified device. work_out[5) of vq_extnd (66H), 
described in Section 8, indicates the availability of a color lookup table. 

Input Arguments 

handle Device handle 

index The color index 

rgbjn[0] Red color intensity (in tenths of percent, 0-1000) 

rgbjn[1] Green color intensity (in tenths of percent 0-1000) 

rgbjn[2] Blue color intensity (in tenths of percent, 0-1000) 

Sample Call to Language Bindin g 

WORD vs_color(); 

WORD handle. Index, rgbjn[3]; 

vs_color(handle, index, rgbjn); 
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Parameter Block Binding 

Control Input Output 

control(O) = 14 intin(O) = index 

control(l) = intind) = rgbJnlO) 

control(2) = intin|2) = rgbJnjll 

controlO) = 4 intin(3) = rgbjn(2l 
control(4) = 
controKS) = 
control(6) = handle 
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VSL_TYPE (FH) 

This function sets the line type for subsequent polyline operations. All 
devices support at least six polyline types; the total number of 
available line types is device-dependent. v_opnwk (IH) and v_opnvwk 
(64H) return the number of line types for a particular device in 
work_out[6]. 

The line type index values and their corresponding pattern word bit 
settings are listed in Table 5-3. The pixel value in the pattern word is 
1 = pixel on (active); = pixel off, the most significant bit Is the first 
pixel displayed. 



Table 5-3. Line Type Index Values and Pattern Words 



Value Style 



Line Pattern Word 



1 


Solid 


2 


Long dash 


3 


Dot 


4 


Dash,dot 


5 


Dash 


6 


Dash.dotdot 


7 


User-defined 


8-n 


Device- 




dependent 



MSB LSB 

1111111111111111 FFFFH 

1111111111110000 FFFOH 

1110000011100000 EOEOH 

1111111000111000 FE38H 

111111110 0000000 FFOOH 

1111000110011000 F198H 
See vsLudsty (71H) on page 5-10 



By default at open workstation, the user-defined line style is set to the 
pattern word for a solid line. This default assignment can be changed 
with vsLudsty (71H). 

vsLtype returns the line type selected and uses a solid line (1) if the 
value specified by the calling routine is out of range. 

Note: if a nondefault line width is used, the device may draw the 
thickened line using a solid line style and may change the writing 
mode. Check the Information returned by vq.extnd (66H) in 
work_out[17j and work_out[18]; vq_extnd is described in Section 8, 
"Inquire Functions." 
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Input Arguments 

handle Device handle 

style Requested line type, see Table 5-3 

Output Arguments 

set_type Line type selected 

Sample Call to C Language Binding 

WORD vsLtypeO; 

WORD set.type, handle, style; 

set_type = vsLtype{handle, style); 
Parameter Block Binding 

Control Input Output 

control(O) = 15 intin(O) = style Intout(O) = set_type 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

control(5) = 

control(6) = handle 
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VSL.UDSTY (71H) 

v_udsty sets the user-defined line style pattern word In the device 
driver to the specified pattern word (16-bits). This line is used for 
subsequent polyline operations when an application selects the user- 
defined line style, index 7. 

The Most Significant Bit (MSB) of the pattern word is the first pixel 
displayed in the line; see Table 5-3 on page 5-8. 

When the workstation is opened, the default for the user-defined line 
style is a solid pattern word. 

input Arguments 

handle Device handle 

pattern Line style pattern word, 16 bits 

Sample Call to C Language Binding 

WORD vsLudstyO; 
WORD handle, pattern; 

vsLudsty(handle, pattern); 
Parameter Block Binding 

Control Input Output 

controMO) = 113 intin(O) = pattern 

controKD = 

control(2) = 

controlO) = 1 

control(4) = 

control(5) = 

control(6) = handle 
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VSL_WIDTH (lOH) 

This function sets the line width for subsequent polyline operations. 
The available line width closest to, but not greater than, the requested 
line width is used. Line widths are odd numbers that begin at one. If 
you select two in Raster Coordinates, vsl_width returns one, which 
sets the line width at one pixel. 

vqLattributes (23H), described In Section 8, "Inquire Functions," returns 
the current line width in work_out[5]. 

Note: Thickened lines might be rendered on the device by selecting a 
solid line type (1). 

Input Arguments 

handle Device handle 

width Requested line width in x-axis NDC/RC units 

Output Arguments 

set_width Selected line width in x-axis NDC/RC units 

Sample Call to Language Binding 

WORD vsLwidthQ; 

WORD set.width, handle, width; 

set_width = vsLwidth(handle, width); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 16 ptsin(O) = width ptsout(O) = set-width 

controKD = 1 ptsin(l) = ptsout(l) = 

control|2) = 1 

controlO) = 

control(4) = 

control|5) = 

control(6) = handle 
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VSL^COLOR (11H) 

vsLcolor sets the color Index for subsequent polyline operations. The 
vs_color (EH) function determines the color the index represents. 

At least two color indices, and 1, are always supported 
(monochrome). Color indices range from to a device-dependent 
maximum, vsl.color returns the color index selected and uses color 
index 1 if the calling process specifies an index that is out of range. 

The default color table index values are listed in Table 3-3 on page 
3-4. 



Input Arguments 

handle Device handle 

colorjndex Requested color index 

Output Arguments 

set.color Color index selected 

Sample Call to Language Binding 

WORD vsLcolorO; 

WORD set_color, handle, colorjndex; 

set_color = vsLcolor(handle, colorjndex); 
Parameter Block Binding 

Control Input Output 

control(O) = 17 Intin(O) = colorjndex Intout(O) = set_color 

controHD = 

control(2) = 

controiO) = 1 

control(4) = 1 

controKS) = 5 

control(6) = handle 
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VSL.ENDS (6CH) 

This function sets the style for the beginning and ending points of a 
polyiine. The two points of a polyline can have different styles. The 
calling routine can specify the end styles listed in Table 5-4. 



Table 5-4. Polyline End Styles 



Value End Style 






Squared (Default) 


1 


Arrow 


2 


Rounded 



If the calling routine requests an invalid end style, vsi.ends uses 
squared (0). 

Both the squared and arrow styles end at the end of the polyline. The 
rounded style is drawn so that the center of the rounding is at the end 
of the polyline; see Figure 5-1. 
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Figure 5-1. Points for Polyline End Styles 
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Input Arguments 

handle Device handle 

beg.style End style for beginning point, see Table 5-4 

end.style End style for ending point 

Sample Call to C Language Binding 

WORD vsLendsO; 

WORD handle, beg^style, end.style; 

vsLends(handie, beg_style, end_style); 
Parameter Block Binding 

Control Input Output 



control(O) = 108 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 



intin(O) = beg.style 
intin(l) = end_style 



control(6) = handle 
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VSM^TYPE (12H) 

vsmJYPe sets the marker type for subsequent polymarker functions. 
Although the total number of available marker types is device- 
dependent, the VDI always defines at least six. The marker types are 
listed in Table 5-5. 



Table 5-5. Polymarker Types 



Value Type 



1 


Dot 


2 


Plus 


3 


Asterisk (Default) 


4 


Square 


5 


Diagonal Cross 


6 


Diamond 


7-n 


User-defined 



v_opnwk (IH) and v_opnvwk (64H) return the number of marker types 
for a particular device In work_out[8l; see Section 3. vqm_attributes 
(24H), described in Section 8, "Inquire Functions," returns the current 
marker type. 

If the marker type requested by the calling routine is out of range, 
vsm_type uses an asterisk, type 3. Marker type 1 Is the smallest dot 
the VDI displays on the device; it cannot be scaled. 
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Input Arguments 

handle Device handle 

symbol Requested polymarker type, see Table 5-5 

Output Arguments 

set_type Polymarker type selected 

Sample Call to C Language Bindrng 

WORD vsm_type(); 

WORD set_type, handle, symbol; 

set_type = vsm_type(handle, symbol); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 18 
controMD = 
control(2) = 
controlO) = 1 
control(4) = 1 
controKS) = 
control(6) = handle 



intin(O) = symbol 



intout(O) = set.tYPO 
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VSM_HEIGHT (13H) 

The polymarker height determined by vsm_height is used for 
subsequent polymarlcer functions. The number of polymarker sizes 
available for a particular device is returned by v.opnwk (1H) and 
v_opnvwk (64K) in work_out[9] — see Section 3. 

If the marker height requested by the calling routine does not exist, 
vsm_helght selects the next smaller height. vsm_height returns the 
actual marker height selected in set.height. 

In put Arguments 

handle Device handle 

height Requested polymarker height In y-axis NDC/RC units 

Output Arguments 

set_height Polymarker height selected in y-axis NDC/RC units 

Sample Call to C Language Binding 

WORD vsm_height(); 

WORD set.height, handle, height; 

set_height = vsm_helght(handle, height); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 19 ptsinIO) = ptsoutIO) = 

control(l) = 1 ptsin(l) = height ptsout(l) = set_height 

control(2) = 1 

controlO) = 

control(4) = 

controKS) = 

control(6) = handle 
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VSM.COLOR (14H) 

vsm.color sets the color index for subsequent polymaricer operations. 
Tiie vs.color (EH) function determines the color the Index represents. 

At least two color indices, and 1, are always supported 
(monochrome). Color indices range from to a device-dependent 
maximum. vsm_color returns the color index selected for the 
polymarker and selects color index 1 if the index specified by the 
calling process is out of range. 

The default color table index values are listed in Table 3-3 on page 
3-4. 



Input Arguments 

handle Device handle 

colorjndex Requested polymarker color index 

Output Arguments 

set.color Selected polymai'ker color index 

Sample Call to C Language Binding 

WORD vsm_color(); 

WORD set_color, handle, colorjndex; 

set_color = vsm_color(handle, colorjndex); 
Parameter Block Binding 

Control Input Output 

control(O) = 20 intin(O) = colorjndex intout(O) = set_color 

control(l) = 

control(2) = 

control(3) = 1 

control(4) = 1 

controMS) = 

control(6) = handle 
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VST_HEIGHT (CH) 

vst_height sets the current graphic text character height in NDC/RC 
units (absolute mode). The character height is specified the according 
to the distance from the character baseline to the top of the character 
cell, rather than the character cell height. 

If the specified character height does not map exactly to a size 
available on device, vst_height selects the closest character size that 
does not exceed the requested size. 

vst_height returns the selected character height (baseline to top line) 
and the size of a character cell; see Figure 5-2. For fixed 
(monospaced) fonts, vst_height returns the width of a character and 
the width of a character cell. For proportional fonts, vst_height returns 
the width of the widest character and the width of the widest 
character cell. 

All input and output arguments are specified in units of the current 
coordinate system (NDC or RC). 
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Figure 5-2. Character Size Definition 
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v_opnwk (IH), v.opnvwk (64H), and vqt_attributes (26H) return 
information about character sizes for the specified device, v.opnwic 
and v.opnvwic are described in Section 3; vqt.attributes is described in 
Section 8. 

Input Arguments 

handle Device handle 

height Requested character height in y-axis NDC/RC units 

Output Arguments 

char.width Character width selected in x-axis NDC/RC units 

char.height Character height selected in y-axis NDC/RC units 

celLwidth Character cell width in x-axis NDC/RC units 

celLheight Character cell height in y-axis NDC/RC units 

Sample Call to Language Binding 

WORD vst_height(); 

WORD handle, height, char.width, char_height, celLwidth, 
celLheight; 

vst_height(handie, height, &char_width, &char_height, SicelLwidth, 
StcelLheight); 

Parameter Block Binding 

Control Input Output 

control(O) = 12 ptsin(O) = ptsout(O) = char_wldth 

controid) = 1 ptsin(l) = height ptsin(l) = char_height 

controt(2) = 2 ptsout(2) » celLwidth 

controlO) = ptsoutO) = celLheight 

control(4) = 
controKS) = 
control(6) = handle 



5-20 



GEM VDI Reference Guide VST_POINT (6BH) 

VST_POINT (6BH) 

This function sets tiie current graphic text character height in printer 
points (points mode). A point is 1/72 of an inch. The character height 
is specified according to the distance between the baseline of one line 
of text and the baseline of the next line of text. This specification is is 
the character cell height. 

If the character height specified by the calling routine does not map 
exactly to a device size, vst_point selects the closest character size 
that does not exceed the requested size. 

vst_point returns the selected point size In set_point. Note that 
vst_point returns the character height, character width, cell height, and 
the cell width in NDC/RC units; see Figure 5-2 on page 5-19. 

For proportional faces, vst_point returns the width of the widest 
character and the width of the widest character cell in the font. 

v_opnwk (1H), v_opnvwk (64H), and vqt.attributes (26H) return 
information about character sizes for the specified device, v.opnwic 
and v.opnvwk are described in Section 3; vqt.attributes is described in 
Section 8. 



Input Arguments 

handle Device handle 

point Character cell height in points 

Output Arguments 

set_point Selected ceil height in points 

char_width Selected character width in x-axis NDC/RC units 

char_height Selected character height in y-axis NDC/RC units 

celLwidth Character cell width in x-axis NDC/RC units 

cell_height Character cell height in y-axIs NDC/RC units 
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Sample Call to C Language Bindin g 

WORD vst_point(); 

WORD set_point, handle, point, char_width, char.height, 
cell_width, cell.height; 

set_point = vst_point(handle, point, 8tchar_width, &char_height, 
&cell_width, &cell_height); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 107 
control(l) - 
controKZ) = 2 
controlO) = 1 
control(4) = 1 
controKS) = 
control(6) = handle 



intin(O) = point 



•ntout(O) = set_point 
ptsout(O) = char.width 
ptsout(l) = char.height 
ptsout(2) = celLwidth 
ptsoutO) = celLheight 
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VST_ROTATION (DH) 

vst.rotation specifies the baseline for subsequent graphic text output 
by requesting an angle of rotation for the character baseline vector. 
The calling routine specifies the angle for the baseline vector in tenths 
if degrees. Figure 5-3 depicts how angles are specified to 
vst_rotation. 

vst.rotation returns the selected baseline vector, which is a best-fit 
match to the requested value. 

The default angle of rotation for the baseline vector is zero degrees 
when the workstation is opened. 

900 



1800 



2700 
Figure 5-3. Angle Specification 

Input Arguments 

handle Device handle 

angle Angle character baseline rotation (In tenths of 

degrees, - 3600) 

Output Arguments 

set_baseline Selected angle of character baseline rotation (in 
tenths of degrees 0-3600) 
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Sample Call to C Language Binding 

WORD vst_rotation(); 

WORD set.baseline, handle, angle; 

set.baseline = vst_rotation(handle, angle); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 13 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 



intin(O) - angle 



intout(O) = set_baseline 
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VST^FONT (15H) 

This function selects a graphic character face for subsequent graphic 
text operations. The calling routine selects a face according to its 
number as listed in Table 5-6. You can load external faces with 
vjoadjonts (77H), described Section 3. 

Note that some faces might not be supported on all devices. Use the 
Inquire Font Name and Index function, vqt.name (82H), to determine 
face names and indices. vqt_attributes (26H) returns the currently 
selected face in work_out[0]; vqt_name and vqt_attributes are described 
in Section 8, "Inquire Functions." v_opnwk (1H) and v_opnvwk (64H) 
both return the number of faces for the device in work_out[10l — see 
Section 3. 



Table 5-6. Face Values and Names 



Value 



Font 



1 


System Face 


2 


Swiss 721 




3 


Swiss 721 


Thin 


4 


Swiss 721 Thin Italic 


5 


Swiss 721 


Light 


6 


Swiss 721 


Light Italic 


7 


Swiss 721 


Italic 


8 


Swiss 721 


Bold 


9 


Swiss 721 


Bold Italic 


10 


Swiss 721 


Heavy 


11 


Swiss 721 


Heavy Italic 


12 


Swiss 721 


Black 


13 


Swiss 721 


Black Italic 


14 


Dutch 801 


Roman 


15 


Dutch 801 


Italic 


16 


Dutch 801 


Bold 


17 


Dutch 801 


Bold Italic 
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Input Arguments 

handle Device handle 

font Number of requested software text face 

Output Arguments 

setjont Number of face selected 

Sample Call to C Language Binding 

WORD vstJontO; 

WORD setjont, handle, font; 

set_font = vst_font(handle, font); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 21 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 



intin(O) = font 



intoutiO] = set_font 
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VST.COLOR (16H) 

This function sets the color index for subsequent graphic text 
operations. The vs_color (EH) function determines the color the index 
represents. 

At least two color indices, and 1, are always supported 
(monochrome). Color indices range from to a device-dependent 
maximum. vst_color returns the color index selected and uses color 
index 1 if the calling process specifies an index that is out of range. 

The default color table index values are listed in Table 3-3 on page 
3-4. 



Input Arguments 

handle Device handle 

colorjndex Requested text color index 

Output Arguments 

set.color Selected text color index 

Sample Call to C Language Bindin g 

WORD vst_colorO; 

WORD set_color, handle, colorjndex; 

set_color = vst_color(handle,colorJndex); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 22 intin(O) = colorjndex intout(O) = set_color 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

controMB) = 

control(6) = handle 
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VST_EFFECTS (6AH) 

This function sets text special effects for subsequently displayed 
graphic text. The following effects are available: 

• thickened 

• light intensity 

• skewed 

• underlined 

• outlined 

• shadowed 

• any combination of the above 

The effect input argunnent is a bit pattern. The attributes set by 
vst.effects correspond to the setting in the six least significant bits. 
Table 5-7 lists the bit assignments. 



Table 5-7. Text Attribute Bit Mapping 

Bit Description 

Thickened 

thickened not selected 

1 set style to thickened 

1 Intensity 

normal intensity 

1 light intensity 

2 Skewed 

skewed not selected 

1 set style to skewed 

3 Underlined 

do not underline 

1 underline text 

4 Outline 

do not outline 

1 outline 

5 Shadow 

no shadow 

1 shadow 
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If effect "= 9 (1001 binary), for example, the text style is set to 
thickened and underlined. 

For effects not supported on a device, vst^effects returns those bits 
set to In set.effect. worlc_out[2] of vq^extnd (66H) returns the 
supported text effects. 

The default text effect when the workstation Is opened is normal 
Intensity. 

Figure 5-4 depicts the five of the special text effects. 



Normal 



Thickened 



Light Intensity 



Skewed 



Underlined 



ABCDE 
ABCDE 



ABCDE 
ABCDE 



Figure 5-4. Graphic Text Special Effects 



Input Arguments 

handle Device handle 

effect Text effect bit pattern 
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Output Arguments 

set_effect 



Text effects actually selected (text effect word with 
the appropriate bits set) 



Sample Call to C Language Bind ing 

WORD vst_effects(); 

WORD set.effect, handle, effect; 

set.effect = vst_effects(handle, effect); 
Parameter Block Binding 

Control Input 



Output 



control(O) = 106 

control(l) = 

control(2) = 

control(3) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 



intin(O) = effect 



intout(O) = set_effect 
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VST^ALIGNMENT (27H) 

vst_alignment sets horizontal and vertical alignment for grapiiic text. 
The horizontal alignment is the direction of the baseline; the vertical 
alignment is perpendicular to the baseline. This function controls the 
positioning of the text string in relation to the graphic text position. 

The default alignment, when the workstation is opened, places the left 
baseline corner of the string at the graphic text position. 

If the calling routine specifies an invalid horizontal alignment, 
vst_alignment selects the default, left justified. vst_alignment selects 
the default vertical alignment, baseline, if the calling routine specifies 
an invalid vertical alignment. 

vqt.attributes (26H) returns the current horizontal and vertical 
alignment settings in work_out[3] and work_out[4], respectively; see 
Section 8, "Inquire Functions." 
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Figure 5-5. Graphic Text Alignment 
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Input Arguments 

handle Device handle 

horjn Horizontal alignment: 

Left justified (default) 

1 Center justified 

2 Right justified 

vertjn Vertical alignment (see Figure 5-5): 

Baseline (default) 

1 Half line 

2 Ascent line 

3 Bottom line 

4 Descent line 

5 Top line 

Output Arguments 

hor.out Selected horizontal alignment 

vert.out Selected vertical alignment 

Sample Call to C Language Binding 

WORD vst_alignment(); 

WORD handle, horJn, vertjn, hor_out vert_out; 

vst_alignment(handle, horJn, vertjn, &hor_out, 8tvert_out); 
Parameter Block Binding 

Control Input Output 

control(O) = 39 intin(O) = horJn intout(O) = hor_out 

control(l) = intin(l) = vertjn intout(l) = vert_out 

controKZ) = 

controlO) = 2 

control(4) = 2 

control|5) = 

control(6) = handle 
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VSFJNTERIOR (17H) 

The fill interior style to be used in subsequent polygon fill operations 
is determined by vsfjnterior. 

vsfjnterior returns the selected fill Interior style. If the calling routine 
specifies an unavailable style, vsfjnterior selects hollow. Hollow style 
fills the Interior with the current background color (color index 0). 
Solid style fills the area with the currently selected fill color. 

vqf_attributes (25H), described in Section 8, returns both the current fill 
interior style and fill style index values. 

Input Arguments 

handle Device handle 

style Fill interior style: 

Hollow 

1 Solid 

2 Pattern 

3 Hatch 

4 User-defined style 

Output Arguments 

setjnterior Selected fill interior style 

Sample Call to C Language Bindin g 

WORD vsfJnteriorO; 

WORD setjnterior, handle, style; 

setjnterior = vsfJnterior(handle, style); 
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Parameter Block Bindin g 

Control Input 



Output 



controi(O) = 23 
control(l) = 
control(2) == 
controiP) = 1 
control(4) = 1 
controKS) = 
control(6) = handle 



intin(O) = style 



intout(O) = setJnterior 
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VSF_STYLE (18H) 

vsf_style selects a fill style based on the fill Interior style determined 
by vsfjnterlor (17H). If the current fill interior style is hollow (0), solid 
(1), or user-defined (4), this function has no effect on the fill style. A 
fill style index can be selected only for the pattern (2) and hatch (3) fill 
interior styles. 

Fill style indices range from 1 to a device-dependent maximum. 
work_out[11] and work_out[12l of v_opnwk (1H) return this maximum; 
see Section 3. If the calling routine specifies an unavailable fill style 
index, vsf_style uses index 1. 

Figure 5-6 shows the available fill styles. Under each fill style shown 
Figure 5-6 are two numbers separated by a comma. The number to 
the left of the comma corresponds to the Interior style: Hollow, 
Pattern, or Hatch. The number to the right of the comma corresponds 
to the Index for the particular pattern or hatch. 
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Figure 5-6. Fill Styles and Indices 





3,9 













3,10 



3,11 



3,12 



Note: 1,n (interior style 1, solid, followed by any index) produces the 
same result as 2,8. 

For patterns, index 1 maps to the lowest intensity pattern on the 
device. The pattern is always monochrome and uses the current fill 
area color for foreground pixels. 
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The number of available pattern and hatch styles is returned in 
work_out[11] and work_out[12], respectively, of v_opnwk (IH) and 
v_opnvwk (64H). These functions are described In Section 3. 

Input Arguments 

handle Device handle 

styleJndex_Fili style index for pattern or hatch interior 

Output Arguments 

set.style Selected fill style index for pattern or hatch interior 

Sample Call to C Language Binding 

WORD vsf_style(); 

WORD set_style, handle, stylejndex; 

set_style = vsf_style(handle, stylejndex); 
Parameter Block Binding 

Control Input Output 

control(O) = 24 intin(O) = style.index intout(O) = set_stvle 

control(l) = 

control(2) = 

control|3) = 1 

control(4) = 1 

control(5) = 

control(6) = handle 
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VSF_COLOR (19H) 

vsf.color sets the color index for subsequent fill operations. Set Color 
Representation, vs_color (EH), determines the color the Index 
represents. 

At least two color indices, and 1, are always supported 
(monochrome). Color indices range from to a device-dependent 
maximum, vsf.color returns the color index selected and uses color 
index 1 if the calling process specifies an invalid index. 

The default color table index values are listed in Table 3-3 on page 
3-4. 



Input Arguments 

handle Device handle 

colorjndex Requested fill color index 

Output Arguments 

set.color Selected fill color index 

Sample Call to Language Binding 

WORD vsf.colorO; 

WORD set_color, handle, colorjndex; 

set_color = vsf_color(handle, colorjndex); 
Parameter Block Binding 

Control Input Output 

control(O) = 25 intin(O) = colorjndex intout(O) = set_coior 

control(l) = 

control(2) = 

control(3) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 
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VSF.PERIMETER (68H) 

vsf .perimeter turns the outline of a fill area on or off. When perimeter 
visibility is on (the default when the workstation is opened), the border 
of a fill area is drawn in the current fill area color with a solid line. 
When perimeter visibilltY is off, no outline is drawn. 

Any nonzero value specified for the perimeter visibility flag, per.vis, 
causes the perimeter to be visible. 

Input Arguments 

handle Device handle 

per_vis Perimeter visibility flag: 

zero Invisible 

nonzero Visibile 

Output Arguments 

set_perimeter Selected perimeter visibility 

Sample Call to C Language Bindin g 

WORD vsf_perimeter{); 

WORD set_perimeter, handle, per_vis; 

set_perimeter = vsf_perimeter(handle, per_vis); 
Parameter Block Binding 

Control Input Output 

intin(O) = per_vis intout(O) = set_perimeter 



controMO) = 


104 


control(l) = 





control(2) = 





controlO) = 


1 


control(4) = 


1 


control(5) = 






control(6) = handle 
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VSF_UDPAT (70H) 

This function redefines the user-definable fill pattern. This fill pattern 
is referenced by vsfjnterior (17H) as fill interior style 4. 

16 two-byte words are required for a single plane fill pattern. Bit 15 
of the first word is the upper left bit of the pattern. Bit of word 16 
is the lower right bit of the pattern. Bit is the Least Significant Bit 
of the word. Words are stored in the same format as 16-blt integers. 

For a single plane pattern, a bit value of 1 indicates foreground color. 
A bit value of indicates the background color. The color used for 
the foreground is determined by the current fill area color index as set 
by vsf.color (19H). 

For a multiple plane pattern (multiple colors), the number of full 16- 
by-16 (words-by-bits) planes defined is used in the fill operation. Any 
unspecified planes are zeroed. Note that the writing mode must be 
set to replace (mode 1) when using a multiplane fill pattern; see 
vswr_mode (20H) on page 5-3. 

The user-defined fill pattern is the DRI logo by default when the 
workstation is opened. 

Input Arguments 

handle Device handle 

pfilLpat Fill pattern data (16 words per plane) 

Sample Call to C Language Binding 

WORD vsf_udpat(); 

WORD handle, planes, pfil_pat[planes x 16]; 

vsf_udpat(handle, pfilLpat, planes); 
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Parameter Block Binding 

Control Input 



control(O) = 112 
control(l) = 
control(2) = 

control(3) = 16-n 
control{4) = 
controKB) = 

control(6) = handle 



ntln(O) 



ntin(15) =ist plane of fill pattern 
ntln(16) 



ntin(2g) = 2"^ plane of fill pattern 
ntin(n-15) 



ntin(n) = last plane of fill pattern 



End of Section 5 
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Raster Operations 



Raster operations perform logic operations on rectangular blocks of 
bits in memory and on rectangular blocks of pixels on physical 
devices. 



Table 6-1. Raster Operation Functions 



Function 


Page 


Purpose 


v_get_pixel (69H) 


6-9 


Get Pixel 


vro_cpyfm (6DH) 


6-10 


Copy raster, opaque 


vrjrnfm (6EH) 


6-12 


Transform form 


vrt_cpyfm (79H) 


6-13 


Copy raster, transparent 
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Memory Form Definition Blocic 

A raster area is defined by a IVIemory Form Definition Blocic (IVIFDB). 
As shown In Figure 6-1, an MFDB consists of ten words; its 
components are as follows: 

• A 32-bit pointer to the memory address of the upper left corner 
of the first plane of the raster area. This pointer is a native- 
machine pointer. If all 32 bits of this pointer are 0, the MFDB is 
for a physical device, and any MFDB parameters you enter are 
ignored — these values are defined In the device driver. 

• The width and height of the raster area in pixels. 

• The width of the raster area in words. This value is equal to the 
width of the raster area in pixels, divided by the word size. 

• A flag indicating whether the format of the raster area is standard 
or device-dependent. 

• The number of memory planes in the raster area. 

• Some locations reserved for future use. 



A raster area must start on a word boundary and have a width that is 
an integral multiple of the word size. 
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Memory Form Definition Blocic 













Word1 


Memory pointer word 1 




Word 2 


Memory pointer word 2 




Word 3 


Form Width in Pixels 




Word 4 


Form Height in Pixels 




Words 


Form Width in Words 




Word 6 


Form format flag 




Word? 


Number of Memory Planes 




Words 


Reserved for future use 




Word 9 


Reserved for future use 




Word 10 


Reserved for future use 





Figure 6-1. Memory Form Definition Biocl( 
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Raster Area Formats 

Two memory formats are associated with raster areas: 

• device-specific format 

• well-defined standard format 

The VDI provides the vr_trnfm (6EH) function to transform a raster area 
from one format to another. You must transform a standard format 
raster area to a device-specific format before using a copy raster 
function, vro.cpyfm (6DH) or vrt_cpyfm (79H). 

The form format flag of the MFDB can have two values: 

The form is In device-specific format 

1 The form is in standard format 

The layout of a standard form format is as follows (see Figure 6-2): 

• Plane based - The planes are contiguous blocks of memory, each 
having the same x,y resolution. A monochrome implementation 
has a single plane. A color index is mapped to a pixel value with 
each plane representing one bit In the value. Tables 6-2 and 6-3 
define the pixel-value-to-color-index mapping for eight-color and 
sixteen-color screens, respectively. 

• The Most Significant Bit in a word (16-bit Integer) Is the leftmost 
bit in the image. Note that the data is stored in the same format 
as 16-bit integers. 

• Words are arranged sequentially along a row. The first word is on 
the left edge of the row. 
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Raster Area Formats 



Wordi 



Msb Lsb 

r- Word 2 



Msb Word 1 Plane 1 
I — Msb Wordi Plane 2 

Msb Wordi Plane 3 



0,0 

Raster 

Coordinates 

Space 



Pixel value of 
Pixel at (0,0) 
Raster Coord. 
Space 




Standard 
Monochrome Form 



Standard 
Color Form 
(3 Planes) 



Figure 6-2. Standard Forms 



Table 6-2. Pixel Value to Color index Mapping for 8-color Screens 



Pixel 
Value 



Color 

Index Color 



000 
001 
010 
Oil 
100 
101 
110 
111 






White 


2 


Red 


3 


Green 


6 


Yellow 


4 


Blue 


7 


IVIagenta 


5 


Cyan 


1 


Black 
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Table 6-3. Pixel Value to Color Index Mapping for 16-color 

Screens 

Pixel Color 

Value Index Color 



0000 
0001 
0010 
0011 
0100 
0101 
0110 
0111 
1000 
1001 
1010 
1011 
1100 
1101 
1110 

1111 



Note: A pixel value of maps to the background color. 

In addition to the MFDB, the copy raster functions vro_cpyfm (6DH) and 
vrt.cpyfm (79H) also take a rectangle as an argument. This allows 
operations on a specified portion of the raster area. A rectangle is 
specified by the x,y coordinates of two diagonal corners. 

Coordinate Systems 

A sample single-plane memory form with a form width of 16 pixels, a 
form height of 8 pixels, and a highlighted rectangle with corners of 
(3,1) and (5,4) is shown in Figure 6-3. 






White 


2 


Red 


3 


Green 


6 


Yellow 


4 


Blue 


7 
5 
8 
9 
10 


Magenta 
Cyan 

Light Grey 
Dark Grey 
Dark Red 


11 


Dark Green 


14 


Dark Yellow 


12 


Dark Blue 


15 
13 
1 


Dark Magenta 
Dark Cyan 
Black 
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Coordinate Systems 
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(3.1 ) (5.4) 
Figure 6-3. Sample Single Plane Memory Form 



Logic Operations 

To provide greatest flexibility, raster operations subject to a logic 
operation take the operation as an argument rather than using the 
logic operation associated with vector primitives. In addition, the 
operations available are greatly expanded to allow more flexibility. 
Table 6-4 lists the available operations with the following conventions: 

• S = source pixel value (0 or 1) 

• D = destination pixel value (0 or 1) 

• D' = destination pixel value after the logical operation 
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Table 6-4. Raster Operation Logic Operations 



IVlode Definition 






D'= 




1 


D'= S AND D 




2 


D'= S AND [NOT D] 




3 


D'= S 


(Replace mode) 


4 


D'= [NOT SI AND D 




5 


D'= D 




6 


D'= S XOR D 


(XOR mode) 


7 


D'= S OR D 




8 


D'= NOT [S OR D] 




9 


D'= NOT [S XOR D] 




10 


D'= NOT D 




11 


D'= S OR [NOT D] 




12 


D'= NOT S 




13 


D'= [NOT Si OR D 




14 


D'= NOT [S AND D] 




15 


D'= 1 
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V_GET_PIXEL (69H) 

This function returns a pixel value and a color index for the pixel 
specified in x and y by the calling routine. 

Color index is the background color. It might not map to pixel value 
in device-specific form. Refer to Tables 6-2 and 6-3 for the colors 
and values. Standard form always maps color index to pixel value 0. 

Note: v_get_pixel may not be supported by all device drivers. 

Input Arguments 

handle Device handle 

X x-coordinate of pixel in RC/NDC units 

y y-coordinate of pixel In RC/NDC units 

Output Arguments 

pel Pixel value in device-specific form 

index Color index 

Sample Call to Language Binding 

WORD v_get_plxel(); 

WORD handle, x, y, pel, index; 

v_get_pixel(handle, x, y, 8ipel, &index); 



Parameter Block Bindin g 



Control 


Input 


Output 


control(O) = 105 


ptsin(O) = X 


intout(O) = pel 


control(l) = 1 


ptsin(l) = y 


intout(l) = Index 


control(2) = 






control(3) = 






control(4) = 2 






control|5) = 






control(6) = handle 
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VRO_CPYFM (6DH) 

Copy Raster Opaque copies a rectangular raster area from source form 
to destination form using the logic operation specified by the calling 
routine. If the source and destination forms are the same, and the 
rectangles overlap, vro.cpyfm copies so that the source rectangle is 
not changed until the corresponding area in the destination has been 
processed. No rotation or transformation occurs as a result of this 
function; the copy is pixel for pixel. 

If the source and destination rectangles are not the same size, 
vro.cpyfm uses the destination as a pointer and the source for the 
size, vq.extnd (66H), described in Section 8, returns scaling ability. 

The source and destination forms must be in device-specific form; see 
vrjrnfm (6EH) in this section. 

All input coordinates (xy[0] to xy[7]) must be specified according to the 
current coordinate system (NDC or RC). 

input Arguments 

handle Device handle 

srcMFDB Double-word address of the source MFDB 

desMFDB Double-word address of the destination MFDB 

wr_mode Logic operation (refer to Table 6-4) 

xy[0] x-coordinate of source rectangle corner in NDC/RC 

xy[l] y-coordlnate of source rectangle corner In NDC/RC 

xy[2] x-coordinate, in NDC/RC, of corner diagonal to xy[0] 

xy[3l y-coordinate, in NDC/RC, of corner diagonal to xy[1] 

xy[4] x-coordinate of destination rectangle corner in 

NDC/RC 

xy[5] y-coordinate of destination rectangle corner in 

NDC/RC 
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xy[6] x-coordinate of destination rectangle corner diagonal 

to xy[4] 

xy[7] y-coordinate of destination rectangle corner diagonal 

to xy[5] 

Sample Call to C Language Binding 

WORD vro_cpyfm(); 

WORD handle, wr.mode, xy[], *srcMFDB, *desMFDB; 

vro_cpyfm(handle, wr_nnode, xy, srcMFDB, desMFDB); 
Parameter Block Binding 

Control Input Output 

control(O) = 109 intln(O) = wr_mode 

control(l) = 4 ptsin(O) = xylOl 

controllZ) = ptsin(l) = xyM) 

control|3) = 1 

control(4) =0 

control{5) = ptsin(7) = xyl?) 

control(6) = handle 

controM7-8) = srcMFDB 

control(9-10) = desMFDB 
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VR_TRNFM (6EH) 

This function transforms a raster area from standard format to device- 
specific format or from device-specific to standard format. The 
operation is a toggle that changes the current format state. 

The number of planes specified in the source IVIFDB determines the 
number transformed. The source format flag is toggled and placed in 
the destination. The user is required to ensure that the other 
parameters in the destination MFDB are correct. 

Note that the source and destination MFDBs must be either completely 
coincident or separate; they cannot partially overlap. 

Input Arguments 

handle Device handle 

srcMFDB Double-word address of the source MFDB 

desMFDB Double-word address of the destination MFDB 

Sample Call to C Language Binding 

WORD vr_trnfm(); 

WORD handle, *srcMFDB, *desMFDB; 

vr_trnfm(handle, srcMFDB, desMFDB); 
Parameter Block Binding 

Control Input Output 

control(O) = 110 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
control|5) = 
control(6) = handle 
control|7-8) = srcMFDB 
control(g-IO) = desMFDB 
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VRT_CPYFM (79H) 

Copy Raster Transparent copies a monociirome rectangular raster area 
fronn tiie source form to a color area. The calling routine specifies a 
writing mode and color indices for both O's and Vs. The source form 
cannot be the screen. 

If the source and destination rectangles are not the same size, 
vrt.cpyfm uses the source rectangle for the size and the upper left 
corner of the destination rectangle for the initial destination location. 

All rectangle coordinates (xyLO] to Ky[1]) must be specified according 
to the current coordinate system (NDC or RC). 

Transfer of Information from the source to the destination is controlled 
by specifying the writing mode as described below. 

Mode 1, Replace 

Replace mode results In a replacement of all pixels in the destination 
rectangle. The foreground color index, specified in index[0], is output 
to ail pixels associated with source locations which are set to one. 
The background color index, specified in index[1]. Is output to all pixels 
associated with source locations set to zero. 



Mode 2, Transparent 

Transparent mode affects only the pixels associated with a source 
value of one. Those pixels are set to the foreground color whose 
Index is specified in index[0]. The color Index specified in index[1] is 
not used. 



Mode 3, XOR 

In XOR mode, the monochrome raster source area is logically XORed 
with each plane of the destination. The specified color indices are not 
used. 
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Mode 4, Reverse Transparent 

Reverse Transparent mode affects only the pixels associated with a 
source value of zero. These pixels are set to the background color 
specified in index[1]. The color index specified in index[0] is not used. 

Input Arguments 

handle Device handle 

srcMFDB Double-word address of the source MFDB 

desMFDB Double-word address of the destination MFDB 
wr_mode Writing Mode: 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 

index[0] Color index for ones in data (foreground) 

lndex[1] Color index for zeros in data (background) 

xy[0] x-coordinate of source rectangle corner in NDC/RC 

xy[1] y-coordinate of source rectangle corner In NDC/RC 

xy[2] x-coordinate, in NDC/RC, of corner diagonal to xy[0] 

xy[3] y-coordinate, in NDC/RC, of corner diagonal to xy[1] 

xy[4] x-coordinate of destination rectangle corner in 

NDC/RC 

xy[5] y-coordinate of destination rectangle corner In 

NDC/RC 

xy[6] x-coordinate, in NDC/RC, of corner diagonal to xy[4] 

xy[7] y-coordlnate. In NDC/RC, of corner diagonal to xy[5] 
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Sample Call to C Language Binding 

WORD vrt.cpyfmO; 

WORD handle, wr_mode, xyll, *srcMFDB *desMFDB, index; 

vrt_cpyfm(handle, wr_mode, xy, srclVIFDB, desIVIFDB, Siindex); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 121 
control(l) = 4 
control(2) = 
controlO) = 
control(4) = 
controKS) = 



control(6) = handle 
control(7-8) = srcMFDB 
control(g-IO) = desMFDB 



intin(O) = wr_mode 
intin(l) = index(0] 
intin(2) = index(1] 
ptsin(O) = xylol 
ptsin(l) = xylll 



ptsini?) = xy|7l 



End of Section 6 
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SECTION 7 
Input Functions 



The VDI input functions allow user interactions with the application 
program. Many of the input functions support two modes: request 
and sample. In request mode, the driver waits until an input event 
occurs before returning. In sample mode, the driver returns the 
current status or location of the input device without waiting. 

In VDI-only programs with multiple workstations, use the request 
mode rather than the sample mode to input characters. Workstations- 
using the sample mode might not get all of the characters input. 

Note: Programs that use both the Application Environment Services 
(AES) and VDI functions must use the AES input functions rather than 
the VDI functions. Use the VDI input functions only in programs that 
do not use the AES. The AES is described in the GEM Application 
Environment Services Reference Guide . 

Table 7-1 lists the VDI input functions. 
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Table 7-1. VDI Input Functions 



Function 



Page 



Purpose 



vrqjocator (1CH) 


7-5 


vsmjocator (ICH) 


7-7 


vrq.valuator (1DH) 


7-9 


vsm.vaJuator (1DH) 


7-11 


vrq.cholce (1EH) 


7-13 


vsm.choice (1EH) 


7-14 


vrq_strlng (IFH) 


7-16 


vsm.string (IFH) 


7-18 


vsln_mode (21H) 


7-3 


vscjorm (6FH) 


7-20 


vexjimv (76H) 


7-22 


v_show_c (7AH) 


7-24 


v_hide_c (7BH) 


7-26 


vq_mouse (7CH) 


7-27 


vex.butv (7DH) 


7-28 


vex.motv (7EH) 


7-30 


vex_curv (7FH) 


7-32 


vq_key_s (80H) 


7-34 



Input locator, request mode 
Input locator, sample mode 

Input valuator, request mode 
input valuator, sample mode 

input choice, request mode 
Input choice, sample mode 

Input string, request mode 
Input string, sample mode 

Set input mode 

Set mouse form 

Exchange timer Interrupt vector 

Show cursor 

Hide cursor 

Sample mouse button state 

Exchange button change vector 

Exchange mouse movement vector 

Exchange cursor change vector 

Sample keyboard state information 



7-2 



GEM VDI Reference Guide VRT.CPYFM (79H) 

VSIN.MODE (21 H) 

vsin_mode sets the input mode to request or sample for the specified 
logical input device. The logical input devices are: 

• locator (mouse, trackball, or joystick) 

• valuator (potentiometer) 

• choice (function keys) 

• string (keyboard) 

Input Arguments 

handle Device handle 

dev_type Logical input device: 

1 Locator 

2 Valuator 

3 Choice 

4 String 

mode Input mode: 

1 Request 

Driver does not return until an input event occurs 

2 Sample 

Driver returns current status or location of the 
input device without waiting 

Sample Call to C Lan guage Binding 

WORD vsin_mode(); 

WORD handle, dev_type, mode; 

vsln_mode(handle, dev_type, mode); 
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Parameter Block Binding 

Control Input 



Output 



control(O) = 33 

controld) = 

control(2) = 

control(3) = 2 

control(4) = 1 

controKS) = 

control(6) = handle 



intin(O) = dev_tvpe 
intin(l) = mode 



intout(O) = Selected mode 
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VRQ_LOCATOR (ICH) 

This function returns the position of the specified locator device in 
request mode. Upon entry to the locator routine, the current cursor 
form is displayed at the initial coordinate. Because vrqjocator 
operates in request mode, it tracks the graphic cursor with the input 
device until a terminating event occurs, which can result from the user 
pressing a key or a button on a mouse, vrqjocator removes the 
cursor when the terminating event occurs. 

Typically, the arrow keys move the cursor in large jumps when used 
without the Shift key and in pixel increments when used with the Shift 
key. If both a keyboard and another locator device are available, the 
cursor is tracked by input from either. This gives the user maximum 
flexibility. 

vrqjocator always displays .a cursor on the screen, even if the cursor 
is currently obscured or hidden. 

Note: This function is not required and might not be supported by all 
device drivers. 



Input Arguments 

handle Device handle 

initx Initial x-coordinate of locator in NDC/RC units 

inity Initial y-coordinate of locator in NDC/RC units 
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Output Arguments 

xout Final x-coordinate of locator in NDC/RC units 

yout Final y-coordinate of locator In NDC/RC units 

term Locator terminator 

The low byte contains a character terminator. For 
keyboard-terminated locator input, this Is the ASCII 
character code of the key that was struck to 
terminate Input. For nonkeyboard-terminated input 
(tablet or mouse for example), valid locator 
terminators begin with 20H (space) and Increase from 
there. For instance, if the puck on a tablet has 4 
buttons, the first button must generate 20H as a 
terminator, the second 21 H, the third 22H, and the 
fourth 23H. 

Sample Gail to Language Binding 

WORD vrqJocatorO; 

WORD handle, Inltx, Inity, xout, yout, term; 

vrqJocator(handle, Initx, Inity, 8ixout, &yout, &term); 
Parameter Blocic Binding 

Control Input Output 

control(O) = 28 ptsin(O) = initx intout(O) = term 

control(l) = 1 ptsin(l) = inity ptsout(O) = xout 

controt(2) = 1 ptsoutd) = yout 

controlO) = 
control(4) = 1 
control(5) = 
control(6) = handle 
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VSM^LOCATOR (ICH) 

vsmjocator returns the position of the specified locator device. Input 
is sampled. Upon entry to the locator routine, no cursor is displayed. 
Use v_show_c (7AH), described on page 7-24, to display the cursor. If 
the cursor position has changed, vsmjocator returns the cursor 
position; if a terminating event occurred, vsmjocator returns a 
character. See Table 7-2 for the appropriate settings of control(2) and 
control(4). 

Note: This function is not required and might not be supported by all 
device drivers. If both a keyboard and another locator device are 
available, the input comes from either, giving the user maximum 
flexibility. 

Input Arguments 

handle Device handle 

initx Initial x-coordlnate of locator in NDC/RC units 

inity initial y-coordinate of locator in NDC/RC units 

Output Arguments 

xout New x-coordinate of locator in NDC/RC units 

yout New y-coordinate of locator In NDC/RC units 

term Locator keypress if keypress occurs 

This information is the same as for vrqjocator (ICH), 
see page 7-5. 
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Table 7-2. Sample Mode Status Returned 



Event 


Control(2) 


Control(4) 


Coordinates changed 




1 





Key pressed; coordinates 
unchanged 







1 


No input 










Key pressed; coordinates 
changed 




1 


1 


Sample Call to C Language Binding 







WORD vsmJocatorO; 

WORD handle, initx, inity, xout, yout, term; 

vsmJocator(handle, initx, inity, &xout, Scyout, &term); 



Parameter Block Binding 

Control 



Input 



Output 



control(O) =28 
control(l) = 1 
ccntrol(2) = 1 coordinate changed 

no coordinate changed 
controlO) = 

control(4) = no keypress character 

1 keypress character returned 
controKS) = 

control(6) = handle 



ptsin(O) = X 
ptsin(l) = y 



intout(O) = term 
ptsout(O) = xout 
ptsout(l) = yout 
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VRQ_VALUATOR (IDH) 

This function returns the value of the valuator device. Because it 
operates in request mode, vrq_valuator increments or decrements the 
initial value of the valuator until a terminating character is struck. 

Valuator keys are typicallY the up-arrow and down-arrow keys. 
Valuator numbers range from 1 to 100. Typical implementation of the 
up-arrow and down-arrow keys Is as follows: 

• Pressing the up-arrow key adds ten to the valuator. 

• Pressing the down-arrow key subtracts ten from the valuator. 

• Pressing the up-arrow key with the Shift key adds one to the 
valuator. 

• Pressing the down-arrow key .with the Shift key subtracts one 
from the valuator. 

Note: vrq_valuator is not required and might not be supported by all 
device drivers. 



Input Arguments 

handle Device handle 

valjn Initial value 

Output Arguments 

vaLout Output value 

term Terminator 
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Sample Call to C Lan g uage Bindin g 

WORD vrq.vaiuatorO; 

WORD handle, valjn, val_out, term; 

vrq_valuator(handie, valjn, 8tvaLout, Stterm); 
Parameter Block Binding 

Control Input Output 

control(O) = 29 intin(O) = valjn intout(O) = vaLout 

control(l) = intout(l) = term 

control(2) = 

controlO) = 1 

control(4) = 2 

control(5) = 

control(6) = handle 
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VSM_VALUATOR (1DH) 

vsm_valuator returns the current value of the valuator device In 
sample mode. If the valuator has changed, vsm.valuator increments 
or decrements the valuator value as required. If a terminating event 
occurs, vsm.vaiuator returns the value. If nothing happens, the 
function does not return a value. 

Valuator numbers range from 1 to 100. The suggested keys are the 
same as for vrq_valuator (1DH); see page 7-9. 

Note: This function is not required and may not be available on all 
devices. 



Input Arguments 

handle Device handle 

valjn Initial value 

Output Arguments 

val_out New valuator value 

term Keypress, if keypress event occurred 

status Terminating status: 

Nothing happened 

1 Valuator changed 

2 Keypress character 



Sample Call to C Langua g e Bindin g 

WORD vsm_valuator(); 

WORD handle, valjn, val_out, term, status; 

vsm_valuator(handle, valjn, &vaLout, 8tterm, 8tstatus); 
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Parameter Block Bindin g 

Control Input 



Output 



control(O) = 29 
control(l) = 
control(2) = 
control(3) = 1 
control(4) = status 
controKS) "= 
control(6) = handle 



intln(O) = valjn 



intout(O) = vaLout 
intout(l) = term 
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VRQ.CHOICE (1EH) 

Operating in request mode, this function returns the status of the 
selected choice device (function key), vrq.choice samples input until a 
key is pressed; if a valid choice key is pressed, vrq.choice returns its 
value. Otherwise, vrq_choice returns the initial choice number. 

Choice numbers range from one to a device-dependent maximum 
value. v_opnwk (IH) and v_opnvwk return the number of choice 
devices in work_out[42]; see Section 3. 

Note: This function is not required and might not be supported by all 
device drivers. 



Input Arguments 

handle Device handle 

in.choice Initial choice number 

Output Arguments 

out_chioce Choice key number 

Sample Call to Language Binding 

WORD vrq_choice(); 

WORD handle, in_choice, out_choice; 

vrq_choice(handle, in.choice, 8tout_choice); 
Parameter Block Binding 

Control Input Output 

control(O) = 30 intin(O) = in_choice intout(O) = out_choice 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

control(5) = 

control(6) = handle 
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VSM.CHOICE (IE) 

vsm.choice returns the choice status of the selected choice device. 
Upon entry to the routine, vsm.choice samples input. If input is 
available and is a valid choice key, vsm.choice returns it Choice 
numbers range from one to a device-dependent maximum value, 
v.opnwk (1H) and v.opnvwk return the number of choice devices in 
work_out[42]; see Section 3. 

Note: This function is not required and may not be available on all 
devices. 

Input Arguments 

handle Device handle 

Output Arguments 

choice Choice number if sample successful, if 

unsuccessful 

status Choice status: 

Nothing happened 

1 Sample successful 

Sample Call to C Language Binding 

WORD vsm_choice(); 
WORD handle, choice; 

vsm_choice(handle, 8(Choice); 
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Parameter Block Binding 

Control Input 



Output 



control(O) = 30 
controld) = 
control(2) = 
controlO) = 
control(4) = status 
control(5) = 
controKG) = handle 



intout(O) = choice 
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VRQ_STRING (IFH) 

Operating in request mode, vrq_strlng returns a string from tiie 
specified device. Input is accumulated until vrq.string encounters a 
carriage return or the intout array is full (maximum string length has 
been reached). 

If the calling routine enables echo mode, text will be echoed to the 
screen with the current text attributes using the vertex passed in 
echo.yx as the justification point. Note that echo mode might not be 
available on all devices, vqt.attributes, described in Section 8, returns 
the current text attributes. 

If the number passed as the maxiumum string length is negative, the 
output string values returned by vrq.string conform to the standard 
keyboard defined in Appendix D. In this case, the absolute value of 
length is used as the maximum string size. 

Note: Echo mode might not be available on all devices. 

Input Arguments 

handle Device handle 

length Maximum string length 

echo.mode Echo mode: 

No echo 

1 Echo input characters at specified position 

echo_xy x- and y-coordinates of echo area In NDC/RC units 

Output Arguments 

string Output string returned in ADE 

The string is word-oriented for the Parameter Block Binding. For the C 
Binding, the string is byte-oriented and null-terminated; its length 
includes an additional byte for the terminating null. 
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Sample Call to C Language Binding 

WORD vrq_string(); 

WORD handle, length, echo_mode, echo_XY[l; 

BYTE *string; 

vrq_string(handle, length, echo_mode, echo_xy, string); 
Parameter Block Binding 

Control Input Output 

control(O) = 31 intin(O) = length intout = string 

control(l) = 1 intin(l) = echo_mode 

control(2) = ptsin{0) = echo_;(vlO) 

controlO) = 2 ptsln(l) = echo_xv(l) 

control(4) = string length 

controt(5) = 

control(6) = handle 
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VSM.STRING (1FH) 

vsm.string returns a string from the specified device. Upon entry, 
vsm.string samples input; if data is available, it Is accumulated, and 
the function samples the input again, vsm.string accumulates input 
until one of the following events occurs: 

• data is no longer available 

• a carriage return is encountered 

• the maximum string length is reached 

If the string will always be terminated with RETURN, use vrq_string 
(IFH); see page 7-16. 

If the calling routine enables echo mode, text will be echoed to the 
screen with the current text attributes using the vertex passed in 
echo_yx as the justification point, vqt.attributes, described in Section 
8, returns the current text attributes. 

Note: Echo mode might not be available on all devices. 

If the number passed as the maxiumum string length is negative, the 
output string values returned by vrq.string conform to the standard 
keyboard defined in Appendix D. In this case, the absolute value of 
the length argument is used as the maximum string size. 

input Arguments 

handle device handle 



length 



Maximum string length 



echo_mode Echo mode: 



echo_xy 



No echo 

1 Echo input characters at the specified position 

X- and y-coordinates of echo area In NDC/RC units 



7-18 



GEM VDI Reference Guide 



VSM_STRING (IFH) 



Output Arguments 

string Output string, if sample successful 

The string is word-oriented for the Parameter Block 
Binding. For the C Binding, the string is byte- 
oriented and null-terminated; Its length includes an 
additional byte for the terminating null. 

status Length of output string: 

Sample unsuccessful (characters not available) 

>0 Sample successful (characters available) 

Sample Call to C Language Binding 

WORD vsm_string(); 

WORD status, handle, length, echo_mode, echoj<y[]; 

BYTE *string; 

vsm_string(handle, length, echo_mode, echo_xy, string, &status); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 31 
control(l) = 1 
control(2) = 
controlO) = 2 
control(4) = status 
controKS) = 
controMG) = handle 



intln(O) = length 
intin(l) = echo_mode 
ptsin(O) = echo_xy(0) 
ptsin(l) = echo_xv(1) 



intout = string 
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VSC_FORM (6FH) 

vsc_form redefines the cursor pattern displayed during locator input or 
at any time the cursor is shown (see the description of v_show_c 
(7AH) on page 7-24). 

The size of the cursor is 16 by 16 pixels; it is defined by two arrays, 
cursor mask and cursor data. For the cursor mask and data, bit 15 of 
word 1 is the upper left bit of the pattern. Bit of word 16 is the 
lower right bit of the pattern. Bit zero is the Least Significant Bit of 
the word. 

The hot spot is the location of the pixel (relative to the upper left pixel 
of the mouse form) that lies over the pixel whose address is returned 
by the input locator function. The hot spot determines the location of 
the cursor; its coordinates are specified in cur_form[0] and cur_form[1]. 

The mouse form is drawn as follows: 

1. The data under the mouse form is saved so that it can be 
restored when the cursor moves. 

2. 1's in the mask cause the corresponding pixel to be set to the 
color index designated in cur_form[3]. 

3. 1's in the mouse form data cause the corresponding pixel to be 
set to the color index designated in cur_form[4]. 
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Input Arguments 

handle Device handle 



cur_form[0] 
cur_form[l] 
cur_form[2] 
cur_fornn[3] 
cur_form[4] 
cur_fornn[5] 

to 
cur_form[20l 
cur_form[21] 

to 
cur_form[36] 



x-coordlnate of hot spot 
y-coordinate of hot spot 
Reserved for future use, must be 1 
Mask color index, normally 
Data color index, normally 1 



16 words of 16-bit cursor mask 



16 words of 16-bit cursor data 



Sample Call to C Langua g e Bindin g 

WORD vscJormO; 

WORD handle, cur_form[37]; 

vsc_form{handle, curjorm); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 111 
controUD = 
controMZ) = 
controlO) = 37 
control{4) = 
controKS) = 
controKB) = handle 



intin(O) = cur_formlOl 



intJn(36) = cur_form(36| 
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VEX_TIMV (76H) 

vex.timv allows the application to perform some action each time a 
timer tick occurs. 

Input to this function Is a two-word pointer, tim_addr, that indicates 
the starting address of the application-dependent code that is to 
receive control when a timer ticl< occurs, vexjimv returns the address 
of the old timer routine in old.addr and the number of milliseconds 
per timer tick in scale. 

The application-dependent code is invoked with a processor- 
dependent instruction. When this is complete, the application should 
perform a processor-dependent return instruction. See Appendix E for 
processor specific instructions and register names. 

Note: It is the responsibility of the application-dependent code to 
save and restore any registers used. When the application code is 
invoked, interrupts are disabled. The application should not enable 
interrupts. 

This function is available only to the application that opened the 
physical workstation. The device handle must be the "root" or physical 
device handle. 

Input Arguments 

handle Physical device handle 

tim_addr Address of application timer routine 

Output Arguments 

old.addr Address of the old timer routine 

scale Milliseconds per tick 
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Sample Call to C Language Bindin g 

WORD vex_timv(); 
WORD handle, scale; 
LONG tim.addr, old_addr; 

vex_tlmv(handle, tim_addr, 8(Old_addr, 8(scale); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 118 intout(O) = scale 

control(l) = 

control(2) = 

controlO) = 

control{4) = 1 

controllS) = 

control(6) = handle 

control|7-8) = tlm_addr 

control|9-10) = old_addr 



7-23 



VEX.TIMV (76H) GEM VDI Reference Guide 

V_SHOW_C (7AH) 

v_show_c displays the current cursor. The cursor moves on the 
display surface based on information input from a mouse. 

v_show_c and v_hide_c (7BH) are closely related. Once the cursor is 
visible, a single v_hide_c call removes the cursor from the display 
surface. The VDI keeps track of the number of times v__hide_c is 
called. v_show_c must be called the same number of times for the 
cursor to reappear. For example, if v.hide.c is called four times, 
v_show_c must be called four times for the cursor to appear. 

v_show_c does, however, provide a reset flag. If the calling routine 
sets the flag is zero, the cursor appears on the screen regardless of 
the number of v_hlde_c calls. A nonzero value for the reset flag 
affects v_show_c as described above. 

Input Arguments 

handle Device handle 

reset Reset flag: 

zero Ignore number of v_hide_c calls 

nonzero Normal v_show_c functionality 

Sample Call to C Language Binding 

WORD v_show_c(); 
WORD handle, reset; 

v_show_c(handle, reset); 
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Parameter Block Binding 

Control Input 



Output 



controi(O) = 122 
control(l) = 
control(2) = 
controlO) = 1 
control{4) = 
controKS) = 
control(6) = handle 



Intin(O) = reset 
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V_HIDE_C (7BH) 

v_hicle_c removes the cursor from the display surface. This state is 
the default condition set when the device is opened with v.opnwk (1H) 
or v_opnwvk (64H). The cursor can appear In a new position when the 
application calls v_show_c (7AH) because the VDI updates the cursor 
position based on information input from a mouse. 

See the description of v_show_c on page 7-24 for a discussion of how 
the number of v_hide_c calls affects the v_show_c function. 



Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_hide_c(); 
WORD handle; 

v_hide_c(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 123 
control(l) = 
control(2) = 
control{3) = 
control(4) = 
control(5) = 
control(6) = handle 
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VQ_MOUSE (7CH) 

vq.mouse returns the current state of the mouse buttons. The state 
of the leftmost mouse button is returned in the Least Significant Bit of 
status. A bit value of indicates the button is up; a bit value of 1 
indicates the button is currently being pressed. 

This function also returns the current (x,y) position of the cursor. 

Input Arguments 

handle Device handle 



Output Arguments 

status Mouse button state: 

Button up 

1 Button pressed 

px X position of cursor in NDC/RC units 

PV Y position of cursor in NDC/RC units 

Sample Call to Language Binding 

WORD vq_mouse(); 

WORD handle, status, px, py; 

vq_mouse(handle, 8(Status, 8(px, 8(py); 
Parameter Block Binding 

Control Input Output 

control(O) = 124 intout(O) = status 

control(l) = ptsout(O) = px 

control(2) = 1 ptsout(l) = py 

controlO) = 

control(4) = 1 

control|5) = 

control(6) = handle 
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VEX_BUTV (7DH) 

With vex_butv, the calling routine can designate the address of 
application-dependent code that is to receive control each time the 
state of the mouse buttons changes. This function passes control to 
the application-dependent code after the button state is decoded, but 
before the driver button state changes. 

Input to vex_butv is a two-word pointer, usercode. This argument 
indicates the starting address of the code to receive control when the 
mouse button state changes, vex.butv returns a two-word pointer, 
savecode, to the old mouse routine. 

Control is passed to the specified address whenever the mouse button 
state changes. The application code is invoked via a processor- 
dependent instruction; a processor-dependent register contains the 
mouse button keys. Keys are encoded by the same rules that apply to 
the vqmouse (7CH) function. When complete, the application- 
dependent code should perform a processor-dependent return 
instruction with the mouse button state the driver is to store in the 
same register. This gives the application the opportunity of altering 
the buttons before they are used by the driver. 

See Appendix E for processor-specific instructions and register names. 

Note: It is the responsibility of the application-dependent code to 
save and restore any registers used. When the application-dependent 
code is invoked, interrupts are disabled. The application should not 
enable interrupts. 

This function is available only to the application that opened the 
physical workstation. The device handle must be the root or physical 
device handle. 



Input Arguments 

handle Physical device handle 

usercode Address of application mouse button state change 
routine 
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Output Arguments 

savecode Address of old mouse button state change routine 

Sample Call to C Language Binding 

WORD vex.butvO; 

WORD handle; 

LONG usercode, savecode; 

vex_butv(handle, usercode, Sisavecode); 
Parameter Block Binding 

Control Input Output 

controMO) = 125 
control{l) =0 
control(2) =0 
controlO) = 
control|4) = 
control|5) =0 
control(6) = handle 
control(7-8) = usercode 
control(9-10) = savecode 



7-29 



VEX.BUTV (7DH) GEM VDI Reference Guide 

VEX_MOTV (7EH) 

vex.motv allows the calling routine to designate the address of 
application-dependent code that is to receive control each time the 
mouse moves to a new location. The application-dependent code 
receives control after the x,y address is computed, but before the 
current mouse position in the driver is updated or the mouse form is 
actually redrawn on the screen. 

Input to this function is a two-word pointer, usercode. This argument 
indicates the starting address of the code to receive control when the 
mouse moves. vex_motv returns a two-word pointer, savecode, to the 
address of the old mouse movement routine. 

When the mouse moves, the application-dependent code is invoked 
via a processor-dependent instruction. The new x and y locations are 
contained in processor-dependent registers. Upon completion, the 
application-dependent code performs a processor-dependent return 
instruction with the x,y mouse position the driver is to store in the 
appropriate hardware registers. This procedure allows the x,y position 
to be altered before it is used by the driver. See Appendix E for 
processor-specific instructions and register names. 

Note: It is the responsibility of the application-dependent code to 
save and restore any registers used. When the application code is 
invoked, interrupts are disabled. The application should not enable 
interrupts. 

This function is available only to the application that opened the 
physical workstation. The device handle must be the "root" or physical 
device handle. 



Input Arguments 

handle Physical device handle 

usercode Address of application mouse movement routine 
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Output Arguments 

savecode Address of the old mouse movement routine 

Sample Call to C Language Bindin g 

WORD vex_motv(); 

WORD iiandle; 

LONG usercode, savecode; 

vex_motv(iiandie, usercode, &savecode); 
Parameter Block Binding 

Control Input Output 

control(O) = 126 
controKD = 
control(2) = 
controlO) = 
control(4) = 
controKB) = 
control(6) = handle 
control(7-8) = usercode 
control(9-10) = savecode 
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VEX_CURV (7FH) 

vex.curv allows the calling routine to designate the address of 
application-dependent code that is to receive control each time the 
cursor is drawn. The application can completely take over drawing the 
cursor or perform some action and then have the VDI draw the cursor. 
Control is passed to the application whenever the cursor position 
should be updated. 

Input to this function is a two-word pointer, usercode. This argument 
indicates the starting address of the code to receive control when a 
cursor Is drawn. vex_curv returns a pointer, savecode, to the address 
of the old cursor draw routine. 

The application-dependent code is invoked with a processor- 
dependent instruction. The x,y position at which the cursor should be 
drawn is contained in a pair of processor-dependent registers. If the 
application-dependent code does not draw its own cursor, a 
processor-dependent call should be performed to the address returned 
in psavcode. This will cause the VDI to draw a cursor. When it is 
done, the application should perform a processor-dependent return 
instruction. See Appendix E for processor-specific instructions and 
register names. 

Note: It is the responsibility of the application-dependent code to 
save and restore any registers used. The VDI cursor draw routine 
preserves the contents of all registers. When the application code is 
invoked, interrupts are disabled. The application should not enable 
interrupts. 

This function is available only to the application that opened the 
physical workstation. The device handle must be the "root" or physical 
device handle. 



Input Arguments 

handle Physical device handle 

usercode Address of application cursor draw routine 
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Output Arguments 

savecode Address of the old cursor draw routine 

Sample Call to C Language Binding 

WORD vex_curv(); 

WORD handle; 

LONG usercode, savecode; 

vex_curv(handle, usercode, 8tsavecode); 
Parameter Block Binding 

Control Input Output 

control(O) = 127 
control(l) = 
control(2) = 
controlO) = 
control|4) = 
controKS) =0 
control(6) = handle 
control|7-8) = usercode 
control(9-10) = savecode 
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VQ_KEY_S (80H) 

vq_key_s returns the current state of the keyboard's Control, Shift, and 
Alt keys as a bit-encoded value in status. The bit assignments are: 

Bit - Right shift key 
Bit 1 - Left shift key 
Bit 2 - Control key 
Bit 3 - Alt key 

Bit is the Least Significant Bit of the word. A bit value of zero 
indicates the key is up, a bit value of 1 indicates that the key is being 
pressed. 

Input Arguments 

handle Device handle 

Output Arguments 

status Keyboard state 

Sample Call to C Language Binding 

WORD vq_key_s(); 
WORD handle, status; 

vq_key_s(handle, Ststatus); 



Parameter Block Binding 

Control Input 



Output 



controllO) = 128 
controUD = 
control(2) = 
controlO) = 
control(4) = 1 
controKS) = 
controi(6) = handle 



intout(O) = status 



End of Section 7 
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Inquire Functions 



The Inquire functions return the current settings for device-specific 
attributes such as color index values, polyline types, and fill area 
styles. 



Table 8-1. VDl Inquire Functions 



Function 


Page 


Purpose 


vq_color (1AH) 


8-2 


Inquire color representation 


vq_cellarray (1BH) 


8-4 


Inquire cell array 


vqLattributes (23H) 


8-6 


Inquire current polyline 
attributes 


vqm.attributes (24H) 


8-8 


Inquire current polymarker 
attributes 


vqf.attributes (25H) 


8-10 


Inquire current fill area attributes 


vqt_attrlbutes (26H) 


8-12 


Inquire current graphic text 
attributes 


vq_extnd (66H) 


8-14 


Return extended device-specific 
information 


vqin.mode (73H) 


8-18 


Inquire input mode 


vqt_extent (74H) 


8-19 


Inquire text extent 


vqt.width (75H) 


8-22 


Inquire character cell width 


vqt_name (82H) 


8-24 


Inquire font name and index 


vqtjontjnfo (83H) 


8-26 


Inquire current font information 


vqtjustified (84H) 


8-29 


Inquire justified graphics text 
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VQ^COLOR (1AH) 

Inquire Color Representation returns the units of RGB intensity 
associated with a color index. You can specify that vq_color is to 
return either the units of RGB intensity as set by a call to vs_color (EH) 
or the actual RGB values used by the device driver (these are the 
realized values selected by the driver if a color is not available). 
vs_color is described In Section 5, "Attribute Functions." 

The Parameter Block (assembly language) binding for vq.coior returns 
-1 in intout(O) if the specified index is out of range. The C binding 
returns only the units of RGB intensity. 

Input Arguments 

handle Device handle 

index Requested color index 

set.flag Set or realized flag: 

set (return RGB intensities for requested index) . 

1 realized (return color values realized on device) 

Output Arguments 

rgb[0] Red intensity (in tenths of percent 0-1000) 

rgb[1] Green intensity 

rgb[2] Blue intensity 

Sample Call to C Language Binding 

WORD vq_color(); 

WORD handle, index, setjiag, rgb[3]; 

vq_color(handle, index, setJIag, rgb); 
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Parameter Block Binding 

Control Input 



Output 



contrl(O) = 26 

contrl(l) = 

contrl{2) = 

contrlO) = 2 

contrl(4) = 4 

contrl(6) = Device handle 



intin(O) = index 
intind) = set_flag 



intout(O) = -1 if index invalid 
intoutd) = rgbtOl 
intout(2) = rgb[1] 
intoutO) = rgb(2] 
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VQ_CELLARRAY (IBH) 

vq.cellarray returns the cell array definition of the specified pixels. 
Color indices are returned one row at a time, starting from the top of 
the rectangular area defined by the pxyarray arguments. vq_cellarray 
returns -1 to indicate that it could not determine a color index for a 
particular pixel. 

All input coordinates are specified according to the current coordinate 
system (NDC/RC). 

Note: This function is not required and may not be supported by all 
devices drivers. 



Input Arguments 

handle Device handle 

pxyarray[0] x-coordinate of rectangle's lower left corner 

pxyarray[1] y-coordinate of rectangle's lower left corner 

pxyarray[2] x-coordinate of rectangle's upper right corner 

pxyarray[3] y-coordinate of rectangle's upper right corner 

rowjength Length of each row in color index array 

num.rows Number of rows in color index array 

Output Arguments 

eLused Number of elements used in each row (number of 

columns) of color index array 

rows_used Number of rows used in color index array 

status Invalid value flag: 

No errors 

1 If a color value could not be determined for some 
pixel 
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colarray[0] Color Index array, stored by row 



colarray[n] Last row of color index 

Sample Call to C Language Binding 

WORD vq_cellarray(); 

WORD handle, pxyarray[4], rowjength, num_rows, eLused, 
rows_used, status, colarray[n]; 

vq_cellarray(handle, pxyarray, rowjength, num_rows, SceLused, 
8irows_used, &status, colarray); 



Parameter Block Binding 



Control 



Input 



Output 



controllO) = 27 
controMD = 2 
control{2) = 
controlO) = 
control(4) = n 
controKS) = 
control(6) = handle 
controM7) = rowjength 
control(8) = num_rows 
controlO) = eLused 
control(IO) = rows.used 
control(ll) = status 



ptsin(O) = pxyarraylOj 
ptsin(l) = pxyarrayd] 
ptsin(2) = pxyarray[2| 
ptsinO) = pxyarray[3] 



intout(O) = colarraylO] 



intout(O) = colarrayln] 
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VQL.ATTRIBUTES (23H) 

vqLattributes returns the current setting of tiie attributes that affect 
polylines. 



Input Arguments 

handle Device handle 



Output Arguments 

attrib[0] Current polyline line type: 



attrib[1] 
attrib[2] 



1 Solid 

2 Long dash 

3 Dot 

4 Dash,dot 

5 Dash 

6 Dash,dotdot 

7 User-defined; see vsl.udsty (71H) on page 5-10 
8-n Device-dependent 

See vsLtype (FH) In Section 5 for more information. 
Current polyline line color index 
Current writing mode: 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 



See vswr_mode 
information. 



(20H) in Section 5 for more 
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attrib[3] End style for beginning point of polyline (not returned 

by C binding): 

Squared 

1 Arrow 

2 Rounded 

attrib[4] End style for ending point of polyline (not returned 

by C binding) 

attrib[5l Current line width. In x-axis NDC/RC units 

Note that only the Parameter Block (assembly language) binding for 
vqLattributes returns the polyline end styles. The C binding returns 
the line type in attrib[0], the line color in attrib[lL the current writing 
mode in attrib[2], and the current line width in attrib[3]. 

Sample Call to C Language Binding 

WORD vqLattributesO; 
WORD handle, attrib[4]; 



vqLattributes(handle, attrib); 
Parameter Block Binding 

Control Input 



Output 



control(O) = 35 
controllD = 
control(2) = 1 
controlO) = 
control(4) = 5 
control|5) = 
controKB) = handle 



intout(O) == attriblO] 
intoutd) = attribdl 
intout(2) = attrib[2| 
intoutO) = attribOl 
intout(4) = attrib[4] 

pstout(O) = attriblS] 
ptsout(l) = 
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VQM_ATTRIBUTES (24H) 

vqm.attrlbutes returns the current setting of the attributes that affect 
polymari^ers. 

input Arguments 

handle Device handle 

Output Arguments 

attrib[0] Current marker type: 

1 Dot 

2 Plus 

3 Asterisk 

4 Square 

5 Diagonal Cross 

6 Diamond 
7-n User-defined 

attrib[1] Current polymarker color index 

attrib[2] Current writing mode 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 

See vswr_mode (20H) in Section 5 for more 
information. 

attrib[3] Current polymarker width, in x-axis NDC/RC units 

attrlb[4] Current polymarker height, In y-axis NDC/RC units 

Note that only the Parameter Block (assembly) binding for 
vqm_attributes returns the current polymarker width. The C binding 
returns the marker type in attrib[0], the marker color index in attrib[1], 
the current writing mode in attrib[2], and the marker height in attrib[3]. 
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Sample Call to C Language Binding 

WORD vqm.attributesQ; 
WORD handle, attrib[4]; 

vqm_attrlbutes(handle, attrib); 
Parameter Block Binding 

Control Input Output 

control(O) = 36 intout(O) - attrib[Ol 

control(l) = intout(l) = attribjl] 

controMZ) = 1 intout(2) = attrib[2l 

controlO) = 

control|4) = 3 ptsoutIO) = attrib[3l 

controKS) = ptsout(l) = attrib[4] 

control(6) = handle 
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VQF_ATTRIBUTES (25H) 

vqf_attrlbutes returns the current setting of the attributes that affect 
fill areas. 



input Arguments 

handle Device handle 



Output Arguments 

attrib[0] Current fill area interior style: 

Hollow 

1 Solid 

2 Pattern 

3 Hatch 

4 User-defined 



attrib[1] 
attrib[2] 

attrib[3] 



See vsfjnterior 
information. 



(17H) in Section 5 for more 



Current fill area color index 

Current fill area style index, refer to vsf_style (18H) 
on 5-35 

Current writing mode: 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 



attrib[4] 



See vswr_mode 
information. 



(20H) in Section 5 for more 



Current fill perimeter status: 



zero 
nonzero 



Invisible 
Visibile 
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Note that only the Parameter Block (assembly) binding for 
aqf.attributes returns the current fill perimeter status. The C binding 
does not return attrib[4]. 

Sample Call to C Language Binding 

WORD vqf.attributesO; 
WORD handle, attrib[4]; 

vqf_attributes(handle, attrib); 



Parameter Block Binding 

Control Input 



Output 



controllO) = 37 
control(l) = 
control(2) = 
controlO) = 
control(4) = 5 
control(5) = 
control(6) = handle 



Intout(O) 
intoutd) 
intout(2) 
intoutO) 
intout(4) 



attriblO] 
attrlbdi 
attrib[2] 
attrlbls] 
attrib(4] 
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VQT_ATTRIBUTES (26H) 

vqt_attributes returns the current setting of all attributes tiiat affect 
graphic text. These attributes include text size, text color, and cell 
dimensions. 



Input Arguments 

handle Device handle 



Output Arguments 

attrib[0] Current graphic text font, see Table 5-6 on 5-25 

attrib[1] Current graphic text color index 

attrib[2] Current angle of rotation of text baseline (in tenths of 

degrees 0-3600) 

attrib[3] Current horizontal alignment: 

Left justified 

1 Center justified 

2 Right justified 

See vst_alignment {27H) in Section 5 for more 
information. 

attrib[4] Current vertical alignment: 

Baseline (default) 

1 Half line 

2 Ascent line 

3 Bottom line 

4 Descent line 

5 Top line 
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attrlb[5] Current writing mode: 

1 Replace mode 

2 Transparent mode 

3 XOR mode 

4 Reverse transparent mode 

See vswr_mode (20H) in Section 5 for more 
information. 

attrib[6] Current character width in x-axis NDC/RC units 

attrib[7] Current character height in y-axis NDC/RC units 

attrib[8l Current character cell width in x-axis NDC/RC units 

attrlb[9] Current character cell height in y-axis NDC/RC units 



Sample Call to Language Bindin g 

WORD vqt_attributes(); 
WORD handle, attrib[10]; 

vqt_attributes(handle, attrib); 
Parameter Block Binding 

Control Input 



Output 



control(O) = 38 

control(l) = 

control(2) = 2 

controlO) = 

control|4) = 6 

controllB) = 

control(6) = handle 



intout(O) = attribiO] 

intout(5) = attrib[5] 
ptsout(O) = attrib(6] 

ptsoutO) = attribOl 
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VQ_EXTND (66H) 

vq_extnd returns an extended set of device-specific information not 
included in the Open Workstation, v_opnwk (1H), function. The 
Information type flag allows the calling routine to specify if vq.extnd is 
to return the v.opnwk output arguments or its extended set of device- 
specific Information. Refer to 3-2 in Section 3, "Control Functions," for 
a description of the values returned by v.opnwk. 

Note that although some values are undefined for the extended set of 
device-specific Information, vq_extnd always returns six output 
vertices and 45 output integers (57 work_out arguments). 

Input Arguments 

handle Device handle 

owflag Information type flag: 

Return Open Workstation, v.opnwk (IH) 
Information 

1 Return extended inquire Information 

Output Arguments 

work_out[0] Type of screen: 

not screen 

1 separate alpha and graphic controllers and 
separate screens 

2 separate alpha and graphic controllers with a 
common screen 

3 common alpha and graphic controller with 
separate image memory 

4 common alpha and graphic controller with 
common image memory 
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VQ.EXTND (66H) 



work_out[1] Number of background colors in color palette 

On some devices, this may be different from the 
number of colors returned by v_opnwk (1H) In 
work_out[39]. 

work_out[2] Supported text effects, bit pattern, see vst_effects 
(6AH) in Section 5 

work_out[3] Scale rasters: 

Scaling not possible 

1 Scaling possible 

work_out[4] Number of planes for raster operations 
work_out[5] Color lookup table support: 

Table not supported 

1 Table supported 

work_out[6] Performance factor, number of 16 x 16 pixel raster 
operations per second 

work_out[7] Contour Fill, v_contourfill (67H), flag: 

Unavailable 

1 Available 

work_out[8] Character rotation support: 

Not supported 

1 90-degree increments only 

2 Arbitrary angles 

work_out[9] Number of writing modes available 
work_out[10] Highest level of input mode available: 

None 

1 Request 

2 Sample 
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work_outIll] Text alignment, vst_alignment (27H), flag: 

Unavailable 

1 Available 

work_out[12] Inking capability flag: 

Device cannot ink 

1 Device can ink 

work_out[13] Rubberbandlng capability flag: 

Device incapable 

1 Capable of rubberband lines 

2 Capable of both rubberband lines and rectangles 

work_out[14] Maximum number of vertices for v_pline (6H), 
v_pmarker (7H), or vjlllarea (9H): 

-1 No maximum 

work_out[15] Maximum length of intin array: 
-1 No maximum 

work_out[16] Number of buttons available on the mouse 
work_outI17] Styles supported for wide lines: 

No 

1 Yes 

work_out[18] Writing modes for wide lines: 

No 

1 Yes 

work_out[19] Clipping, vs_clip (81 H), flag: 

Clipping disabled 

1 Clipping enabled 
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work_out[20l 

to 
work_out[44] 

work_out[45l 
work_out[46] 
work_out[47l 
work_out[48l 



work_out[49l 

to 
work_out[56] 



Reserved, contain zeros 

Upper left x-coordlnate of the clipping rectangle in 
X-axis NDC/RC units 

Upper left y-coordinate of the clipping rectangle in 
y-axis NDC/RC units 

Lower right x-coordinate of the clipping rectangle in 
X-axis NDC/RC units 

Lower right y-coordinate of the clipping rectangle in 
y-axIs NDC/RC units 



Reserved, contain zeros 



Sample Call to C Language Binding 

WORD vq_extnd(); 

WORD handle, owflag, work_out[57]; 

vq_extnd(handle, owflag, work_out); 
Parameter Block Binding 

Control Input 



Output 



control(O) = 102 
controllD = 
control(2) = 6 
control(3) = 1 

control(4) = 45 
controKS) = 

control(6) = handle 



intin(O) = owflag 



intout(O) = work_outlO| 

lntout(44) = work_outl44] 
pstout(O) = work_out(45| 

pstout(ll) = work_outl56l 
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VQIN.MODE (73H) 

vqin.mode returns the current input mode for the specified logical 
device: locator, valuator, choice, or string. 

Input Arguments 

handle Device handle 

dev.type Logical input device: 

1 Locator 

2 Valuator 

3 Choice 

4 String 

Output Arguments 

input_mode Input mode: 

1 Request 

2 Sample 

Sample Call to C Language Binding 

WORD vqin_mode(); 

WORD handle, dev.type, input_mode; 

vqin_mode(handle, dev_type, &input_mode); 
Parameter Block Binding 

control(O) = 115 intin(O) = dev.type intout(O) = input.mode 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

controKS) = 

control(6) = handle 
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VQT.EXTENT (74H) 

vqt.extent uses the current text attributes to calculate tiie dimensions 
of a specified string and returns the coordinates of a rectangle that 
encloses string. The returned vertex coordinates define an extent 
rectangle that touches both the x and y axes. The string is in the first 
quadrant. All text attributes, including style and baseline rotation, 
affect the calculation. 

Output arguments extent[0] to extent[7] specify string points according 
to the current coordinate system (NDC or RC). 




Y-axis 



Figure 8-1. Inquire Text Extent Function 



Input Arguments 

handle Device handle 



string 



Character string as ASCII codes 

The C binding string is byte-oriented and must be 
null-terminated. For the Parameter block binding, the 
string is word-oriented (16-bits). The maximum 
number of characters equals the size of the intin 
array; see work_out[15l of vq extnd (66H). 
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Output Arguments 

extent[0] delta-x for point 1 of string in x-axis NDC/RC units 

extent[1] delta-y for point 1 of string in y-axis NDC/RC units 

extent[2] delta-x for point 2 of string in x-axis NDC/RC units 

extent[3] delta-y for point 2 of string in y-axis NDC/RC units 

extent[4] delta-x for point 3 of string In x-axis NDC/RC units 

extent[5] delta-y for point 3 of string in y-axIs NDC/RC units 

extent[6] delta-x for point 4 of string in x-axis NDC/RC units 

extent[7] delta-y for point 4 of string In y-axIs NDC/RC units 

Sample Call to C Language Binding 

WORD vqt_extent(); 
WORD handle, extent[8]; 
BYTE *string; 

vqt_extent(handle, string, extent); 
Parameter Block Binding 

Control Input Output 

control(O) = 116 intin = string ptsout(O) = extentlO] 

control(l) = 

control(2) = 4 

controtO) = number of ptsout(7) = extent[7] 

chars In string 
control(4) = 
controKS) = 
controi(6) - handle 
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Parameter Block Binding 

Control Input 



Output 



control(O) = 116 
control(l) = 
controllZ) = 4 
control(3) = number of 

chars In string 
control(4) = 
controKS) = 
controKG) = handle 



intin '= string 



ptsout(O) = extentiO] 



ptsout(7) = extentl7l 
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VQT_WIDTH (75H) 

This function returns tiie ciiaracter cell width for a specified character 
in the current font. The character cell width is the distance from the 
left edge of the character to the left edge of the character that follows 
it in a text string; see Figure 8-2. Special effects and rotation do not 
apply. 

vqt.width returns all values in the current coordinate system. 



Left Character 


Right Character 


Alignment 


Alignment 


Delta 


Delta 



Top Line 



Base Line 



W 



Character 
Height 



Cell 
Height 



Cell 
Width 



Figure 8-2. Character Cell Definition 



Input Arguments 

handle Device handle 

character 



ASCII Decimal Equivalent (ADE) value of the character 
in current font 
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Output Arguments 

status ADE value of the specified character; -1 if invalid 

character 

ceiLwidth Cell width of the character in x-axis NDC/RC units 

left_delta Left character alignment delta in x-axis NDC/RC units 

right_delta Right character alignment delta in Y~a><is NDC/RC 
units 

Sample Call to C Language Binding 

WORD vqt_width(); 

WORD status, handle, celLwidth, !eft_delta, right_deita; 
BYTE character- 
status = vqt_width(handle, character, &celLwidth, 
&left_delta, 8(right_deita); 



Parameter Block Binding 

Control Input 



Output 



controllO) = 117 
control(l) = 
control(2) = 3 
controlO) = 1 
control(4) = 1 
controMS) = 

control(6) = handle 



intin(O) = character 



Intout(O) = status 

ptsout(O) = celLwidth 
ptsoutd) = 
ptsout(2) = left.delta 
ptsoutO) = 
ptsout(4) = right_delta 
ptsout(5) = 
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VQT.NAME (82H) 

vqt^name returns a 32-character ASCII Decimal Equivalent (ADE) string 
that describes a specified font. The calling routine specifies a font by 
its element number (1 to the number of fonts available). 

The first 16 characters of the ADE string name the font. The next 16 
characters describe the font's style and weight. The string is null 
terminated. See Table 8-2 for a sample of the possible configurations. 

vqt.name also returns the font index number. This number is used to 
access the font with vstjont (15H). 



Table 8-2. Face Names and Styles 



Face Name 



Styles 



Swiss 721 
Swiss 721 
Dutch 801 
Dutch 801 



Light 

Thin Italic 
Roman 
Bold Italic 



Input Arguments 

handle Device handle 

element.num Element number 
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Output Arguments 

index Font ID number 



name[0] 

to 
name[31] 



32-character ADE string 

For the Parameter Block (assembly language) binding, 
the string -is word-oriented. For the C binding, the 
string is byte-oriented. 



Sample Call to C Language Bindin g 

WORD vqt_name{); 

WORD index, handle, element_num; 

BYTE name[32]; 

index = vqt_name(handle, element_num, name); 



Parameter Block Bindin g 

Control Input 



Output 



control(O) = 130 

control(l) = 

control|2) = 

controlO) = 1 

control(4) = 33 

control{5) = 

control(6) - handle 



intin(O) = element_num 



intout(O) = index 
intout(l) = namelOl 



intout(32) = name(31j 
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VQT_FONTJNFO (83H) 

This function returns size Information for the current font with the 
current size and text effects. 

Because the text effects can change the cell width and extent, 
vqtjontjnfo returns a value (maxwidth) for the maximum cell width 
that excludes any text special effects. This allows the use of the 
width information returned by vqt_wldth (75H). 

When the character is skewed, the cell contains left and right offsets 
as shown in Figure 8-3. 



Left Offset 




Right Offset 



Character Baseline 



Figure 8-3. Skewed Character Offsets 



Input Arguments 

handle Device handle 



Output Arguments 

minADE 



maxADE 



Minimum ADE (ASCII Decimal Equivalent); this is the 
first character in the font 

Maximum ADE, the last character In the font 
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maxwidth Maximum cell width not including special effects 

distances[0] Bottom line distance relative to baseline 

distances[1] Descent line distance relative to baseline in y-axis 
NDC/RC units 

distances[2] Half line distance relative to baseline in y-axis 
NDC/RC units 

distances[3] Ascent line distance relative to baseline in y-axis 
NDC/RC units 

distances[4] Top line distance relative to baseline in y-axis 
NDC/RC units 

effects[0] Special effects delta x, the current special effects 
increase character width by this amount in x-axis 
NDC/RC units 

effects[1] Left offset, positive value relative to position in x-axis 
NDC/RC units (see Figure 8-3) 

effects[2] Right offset in x-axis NDC/RC units (see Figure 8-3) 

Sample Call to C Language Binding 

WORD vqtJontJnfoO; 

WORD handle, minADE, maxADE, distances[5], maxwidth, effects[3]; 

vqt_fontJnfo(handle, 8tmlnADE, &maxADE, distances, Stmaxwldth, 
effects); 
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Parameter Block Binding 

Control input 



Output 



control(O) = 131 
controi(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 



control(6) = handle 



intout(O) = minADE 
intout(l) = maxADE 

ptsout(O) = maxwidth 
ptsout(l) = distanceslO] 
ptsout(2) = effects[0] 
ptsoutO) = distances[l] 
ptsout(4) = effects[l] 
ptsout(5) = dJstances(2] 
ptsout(6) = effects[2l 
ptsout(7) = distancesiS] 
ptsout(8) = 
ptsoutO) = distances[4l 
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VQT_JUSTIFIED (84H) 

Inquire Justified Grapliics Text returns the x- and y-axis offsets for 
each character in a string given a text alignment point and physical 
string length. 

See vjustified (B-AH) on page 4-27 in Section 4 for related 
information. 



Input Arguments 

handle Device handle 

word_space Word spacing flag: 

zero Do not modify inter-word spacing 

nonzero IVIodify inter-word spacing 

char_space Character spacing flag: 

zero Do not modify inter-character spacing 

nonzero Modify inter-character spacing 

string ASCII character string 

X x-coordinate of the text alignment point 

y y-coordinate of the text alignment point 

length Requested length of the string, in x-axis units 
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Output Arguments 

offsets[0] 

offsets[1] 



X-axis offset to base-left of the first character in 
string 

y-axis offset to base-left of the first character in 
string 



offsets[2*n-2l 



offsets[2*n-l] 



X-axis offset to base-left of the last character in 
the string ("n" is used here for the number of 
characters in the string) 

y-axis offset to base-left of the last character in 
the string ("n" is used here for the number of 
characters in the string) 



Sample Call to C Language Binding 

WORD vqtJustifiedO; 

WORD handle, x, y, length, wOrd_space, char_space, string[], 
offsets[]; 

vqtjustified(handle, x, y, string, length, word_space, char_space, 
offsets); 
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Parameter Block Binding 

Control Input 



Output 



control(O) = 132 
controKD = 2 
control(2) = n 
controlO) = 2 + n 
control(4) = 
control(5) = 
control(6) ^^ handle 



intin(O) = word_space 
intin(l) = char_space 
intin(2) = string[0] 



intin(2+n) = stringl2+nl 

ptsin(O) = X 
ptsin(l) = y 
ptsin(2) = length 
ptsinO) = 



ptsout(O) = offsetsIO] 
ptsout(l) = offsetsll] 



ptsout(j) = offsetslj] 



Note: "n" is used here as the number of characters in the string. 



End of Section 8 
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Escape Functions 



The escape functions access the special capabilities of a graphics 
device. The VDI predefines some escape functions, such as those for 
controlling the cursor on an alpha screen. Others, whose opcodes 
must be greater than 5-64H, can be defined for specific devices. 

Table 9-1 lists and briefly describes the VDI escape functions. 



Table 9-1. Escape Function Identifiers 



Function 



Page Purpose 



vq_chcells (5-1 H) 



9-3 



v_exit_cur (5-2H) 


9-4 


v_enter_cur (5-3H) 


9-5 


v.curup (5-4H) 


9-6 


v_curdown (5-5H) 


9-7 


v_curright (5-6H) 


9-8 


v.curieft (5-7H) 


9-9 


v_curhome (5-8H) 


9-10 


v.eeos (5-9H) 


9-11 


v.eeol (5-AH) 


9-12 


vs_curaddress (5-BH) 


9-13 


v_curtext (5-CH) 


9-14 



Return the number of alpha cursor 

addressable rovy^s and columns 

Exit alpha mode for graphics mode 

Exit graphics mode for alpha mode 

Move alpha cursor up one row, 

maintain column position 

Move alpha cursor down one row, 

maintain column position 

Move alpha cursor right one column, 

maintain row position 

Move alpha cursor left one column, 

maintain row position 

Move alpha cursor to home position 

Erase from alpha cursor positon to 

end of screen 

Erase from alpha cursor to end of 

line 

Move alpha cursor to specified 

location 

Display text string at alpha cursor 

location 
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Table 9-1. (Cont'd) 



Function 



Page Description 



v_rvon {5-DH) 9-15 

v.rvoff (5-EH) 9-16 

vq.curaddress (5-FH) 9-17 

vq.tabstatus {5-1 OH) 9-18 

v_hardcopy (5-1 1H) 9-19 

v.dspcur (5-12H) 9-20 

v_rmcur (5-13H) 9-21 

vjorm.adv (5-14H) 9-22 
v_output_window (5-15H) 9-23 

v_clear_dlspjist (5-16H) 9-25 

v.bitjmage (5-17H) 9-26 

vq_scan (5-18H) 9-29 

v.alphajext (5-19H) 9-31 

vs_palette (5-3CH) 9-33 

v.sound (5-3DH) 9-34 

vs.mute (5-3EH) 9-35 

vt.resolutlon (5-5 1H) 9-36 

vt.axis (5-52H) 9-37 

vt_origin (5-53H) 9-38 

vq_tdimensions (5-54H) 9-39 

vt.allgnment (5-55H) 9-40 

vspjilm (5-5BH) 9-41 

vqpjilmname (5-5CH) 9-42 

vsc_expose (5-5DH) 9-44 

vmetaextents (5-62H) 9-45 

vwritemeta (5-63H) 9-46 

vm filename (5-64H) 9-47 



Turn on reverse video 
Turn off reverse video 
Return current alplia cursor address 
Inquire tablet status 
Copy physical screen to printer 
Place graphic cursor at specified 
coordinates 

Remove last graphic cursor 
Form advance 
Output window to printer 
Clear the printer display list 
Print the specified bit image file 
Return printer scan heights and 
number of head passes per page 
Print specified alpha text string 
Select color palette 
Generate specified tone 
Set\Clear tone muting flag 
Set tablet axis resolution in lines/inch 
Set tablet axis resolution in lines 
Set tablet x and y origin 
Return tablet x and y dimensions 
Set tablet alignment 
Set camera film type and exposure 
time 

Inquire camera film name 
Disable or enable film exposure for 
frame preview 

Update extent information in meta- 
file header 

Write a user-defined metafile item 
Use specified filename to rename 
metafile 
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VQ_CHCELLS (5-1 H) 

vq.chcells returns the number of vertical (row) and horizontal (column) 
positions at which the alpha cursor can be positioned on the screen. 
Typically, only screens support alpha text. 

Input Arguments 

handle Device handle 



Output Arguments 

rows Number of addressable rows on the screen, (-1 

indicates cursor addressing not possible) 

columns Number of addressable columns on the screen, (-1 

indicates cursor addressing not possible) 

Sample Call to C Language Bindin g 

WORD vq_chcells(); 

WORD handle, rows, columns; 

vq_chcells(handle, 8trows, 8tcolumns); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intout(O) = rows 

control(l) = intout(l) = columns 

control(2) = 

controlO) = 

control(4) = 2 

control(5) = 1 

control(6) = handle 
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V_EXIT_CUR (5-2H) 

This function causes tiie graphics device to enter graphics mode if 
graphics mode is different from alpha mode. v_exit_cur exits alpha 
cursor addressing mode explicitly, properly transferring from alpha to 
graphics mode, v.exit.cur also clears the graphics screen. 

If the specified device is a metafile, v.exit.cur writes a metafile item to 
the metafile buffer. 



Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_exit_cur(); 
WORD handle; 

v_exlt_cur(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
controi(2) = 
controiO) = 
controKS) = 2 
control(6) = handle 
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V_ENTER„CUR (5-3H) 

v_enter_cur causes the graphics device to exit graphics mode If 
graphics mode Is different from alpha mode. This function enters 
alpha cursor addressing mode explicitly, properly transferring from 
graphics to alpha mode. It also clears the alpha screen. 

v_enter_cur also returns the cursor to the home position on the 
display device. 

If this function is called by a metafile, v_enter_cur writes a metafile 
item to the metafile buffer. 



Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_enter_cur(); 
WORD handle; 

v_enter_cur(handle); 
Parameter Block Binding 

Control Input Output 

controllO) = 5 
control(l) = 
control(2) = 
controiO) = 
control(4) = 
controllS) = 3 
control(6) = handle 
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V_CURUP (5-4H) 

This function moves the alpha cursor up one row without altering its 
horizontal position. If the cursor is already at the top margin, v.curup 
takes no action. 



input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_curup(); 
WORD handle; 

v_curup(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
controi(l) = 
control(2| = 
controlO) = 
control(4) = 
control(5) = 4 
control(6) = handle 
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V_CURDOWN (5-5H) 

v.curdown moves the alpha cursor down one row without altering its 
horizontal position. No action occurs if the cursor is already at the 
bottom margin. 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_curdown(); 
WORD handle; 

v_curdown(handle); 



Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
control(2) = 
controtO) = 
control(4) = 
control(5) = 5 
controKG) = handle 
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V.CURRIGHT (5-6H) 

This function moves the alpha cursor right one column without 
altering its vertical position. If the cursor is already at the right 
margin, v_curright performs no action. 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_curright(); 
WORD handle; 

v_curright(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
controKS) = 6 
control(6) = handle 
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V_CURLEFT (5-7H) 

v.curleft moves the alpha cursor left one column without altering its 
vertical position. This function performs no action if the cursor is 
already at the left margin. 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_curleft{); 
WORD handle; 

v_curleft{handle); 



Parameter Block Binding 

Control Input Output 

control(O) = 5 

controld) = 

control(2) = 

controlO) = 

control(4) = 

control(5) = 7 

control(6) = handle 
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V.CURHOME (5-8H) 

This function moves the alpha cursor to the home position, usually the 
upper left character cell of the display device. 

Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_curhome{); 
WORD handle; 

v_curhome(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) =° 
control(2) = 
controlO) = 
control(4) = 
controKS) = 8 
control(6) - handle 
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V_EEOS (5-9H) 

v_eeos erases the display surface from the current alpha cursor 
position to the end of the alpha screen. The current alpha cursor 
location does not change. 

Input Arguments 

handle Device handle 



Sample Calling to C Language Bindin g 

WORD v_eeos(); 
WORD handle; 

v_eeos(handle); 
Parameter Block Binding 

Control Input Output 

controHO) = 5 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 9 
control(6) = handle 
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V.EEOL (5-AH) 

This function erases the display surface from the current alpha cursor 
position to the end of the current alpha text line. The current alpha 
cursor location does not change. 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v.eeolQ; 
WORD handle; 

v_eeol(handle); 



Parameter Block Binding 

Control fnput Output 

control(O) = 5 
'control(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 10 
control(6) " handle 



9-12 



GEM VDI Reference Guide VS.CURADDRESS (5-BH) 

VS.CURADDRESS (5-BH) 

vs_curaddress moves the alpha cursor directly to the row and column 
specified. The calling routine can specify any location on the display 
surface. vs_curaddress sets addresses beyond the displayable range 
of the screen to the nearest value that is within the displayable range 
of the screen. 

Use vq_chcells (5-1H), described on page 9-3, to determine the 
number of addressable rows and columns. 



Input Arguments 

handle Device handle 

row Row number (1 to maximum number of rows) 

column Column number (1 to maximum number of columns) 

Sample Call to C Language Binding 

WORD vs_curaddress(); 
WORD handle, row, column; 

vs_curaddress(handle, row, column); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 Intin(O) = row 

control(l) = intind) = column 

control(2) = 

controlO) = 2 

control(4) = 

control(5) = 11 

control(6) = handle 
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V.CURTEXT (5-CH) 

v_curtext displays a specified string of alpha text starting at the 
current position of the alpha cursor. It moves the cursor right one 
column for each character in the string. The alpha text attribute 
currently in effect determines how the text is displayed (see v.rvon (5- 
DH) and v_revoff on pages 9-15 and 9-16, respectively). 

The device must be in alpha cursor addressing mode before using 
v_curtext see v_enter_cur (5-3H) on page 9-5. 

Input Arguments 

handle Device handle 

string ASCII Decimal Equivalent (ADE) text string 

The string is word-oriented for the Parameter Block 
binding. For the C binding, the string is byte- 
oriented. 



Sample Call to C Lanugage Binding 

WORD v_curtext(); 
WORD handle; 
BYTE *string; 

v_curtext(handle, string); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin - string 

control(l) = 

control(2) = 

controlO) = n 

control(4) = 

controllS) = 12 

control(6) = handle 
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V_RVON (5-DH) 

This function causes all subsequent alpha text to be displayed in 
reverse video. 



Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD r_von(); 
WORD handle; 

v_rvon(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 

control(l) = 

control(2) = 

controlO) = 

control(4) = 

control|5) = 13 

control(6) = handle 



9-15 



V.RVOFF (5-EH) GEM VDI Reference Guide 

V.RVOFF (5-EH) 

v.revoff displays all subsequent alpha text in normal video format. 

Input Arguments 

handle Device handle 

Sample Call to C Langugage Binding 

WORD v_rvoff(); 
WORD handle; 

v_rvoff(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
controKS) = 14 
control(6) = handle 
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VQ.CURADDRESS (5-FH) 

vq_curaddress returns the current position of the alpha cursor in row, 
column coordinates. 



Input Arguments 

handle Device handle 

Output Arguments 

row Row number (1 to the maximum number of rows) 

column Column number (1 to the maximum number of 

columns) 

Sample Call to C Language Binding 

WORD vq_curaddress(); 
WORD handle, row, handle; 

vq_curaddress(handle, &row, &column); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intout(O) = row 

control(l) = intout(l) = column 

control(2) = 

controlO) = 

control(4) = 2 

controKS) = 15 

controKB) = handle 
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VQ_TABSTATUS (5-1 OH) 

vq.tabstatus returns the availability status of a graphics tablet, mouse, 
joystick, or other similar device. 

Input Arguments 

handle Device handle 



Output Arguments 

status Tablet status: 

Tablet not available 

1 Tablet available 

Sample Call to C Language Binding 

WORD vq_tabstatus(); 
WORD status, handle; 

status = vq_tabstatus(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intout(O) = status 

controMD = 

control(2) = 

controlO) = 

control(4) = 1 

controMS) = 16 

controi(6) = handle 
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V_HARDCOPY (5-1 IH) 

v_hardcopy causes the specified device to generate a hard copy. This 
function is device-specific; it copies the physical screen to a printer or 
other attached hard copy device. 

v_hardcopy is not required and might not be supported by all device 
drivers (see "Required Functions" In Section 2). 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_hardcopy(); 
WORD handle; 

v_hardcopy(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
control(2) = 
contro!(3) = 
control|4) = 
control(5) = 17 
control(6) = handle 
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V_DSPCUR (5-1 2H) 

This function places a grapliic cursor at the location specified by the 
calling routine in the current coordinate system. 

vsc.form (6FH) defines the type of cursor to be displayed. If sample 
mode input is supported, the calling routine can use this function to 
generate the cursor for vsmjocator (1CH), Input Locator-Sample Mode, 
vscjorm and vsmjocator are described in Section 1, "Input Functions." 

v.dspcur applies only to devices capable of locator input (a mouse, 
joystick, or trackball, for example). 

Input Arguments 

handle Device handle 

X x-coordinate of location to place cursor 

y y-coordinate of location to place cursor 

Sample Call to C Language Binding 

WORD v_dspcur(); 
WORD handle, x, y; 

v_dspcur(handle, x, y); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 ptsin(O) = x 

control(l) = 1 ptsin(l) = y 

control(2) = 

controlO) = 

control(4) = 

controt(5) = 18 

control(6) = handle 



9-20 



GEM VDI Reference Guide V.RMCUR (5-13H) 

V_RMCUR (5-1 3H) 

v_rmcur removes the last graphic cursor placed on the screen. 

Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD v_rmcur(); 
WORD handle; 

v_rmcur(handle); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 19 
control(6) = handle 
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V_FORM_ADV (5-1 4H) 

v_form_adv advances the printer page. The VDI requires printer driver 
support of this function. 

Use v_form_adv instead of v_clrwk (3H) when you want issue a form 
feed and retain the current printer display list. 

If the specified device is a metafile, v_form_adv writes a metafile item 
to the metafile buffer. 



Input Arguments 

handle Device handle 

Sample Call to C Language Binding 

WORD vJorm_adv(); 
WORD handle; 

v_form_adv(handle); 
Parameter Block Binding 

Control Input 

control(O) = 5 

control(l) = 

control(2) = 

controlO) = 

control(4) = 

control(5) = 20 

control(6) = handle 
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V_OUTPUT_WINDOW (5-15H) 

This function outputs a rectangular window of a picture to thie printer. 
v_output_window is similar to v_updwk (4H), except that the calling 
routine specifies the coordinates (NDC or RC) of a rectangular window 
area. 

Note that use of this function does not always guarantee that adjacent 
pictures will abut. Pictures will abut with a resolution of one printer 
head height. 

The VDI requires that printer drivers support v_output_window. If the 
specified device is a metafile, v.output.window writes a metafile item 
to the metafile buffer. 



Input Arguments 

handle Device handle 

xyarraytO] x-coordinate of window corner 

xyarrayEU y-coordinate of window corner 

xyarray[2] x-coordinate of corner diagonal to xyarrayEO] 

xyarray[3] y-coordlnate of corner diagonal to xyarray[1] 

Sample Calling to C Language Binding 

WORD v_output_wlndow{); 
WORD handle, xyarray[4l; 

v_output_window{handle, xyarray); 
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Parameter Block Bindin g 

Control Input Output 

control(O) = 5 ptsin(O) = xyarraylO] 

control(l) = 2 ptsln(l) = xyarray[1| 

control(2) = ptsin(2) = xyarray(2] 

controlO) = ptsln{3) = xyarrayOI 

control(4) = 

controKS) = 21 

control(6) = handle 
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V_CLEAR_DISP_LIST (5-1 6H) 

v_clear_disp_list is required only for printers. It Is called to clear the 
printer display list. This function is similar to v.clrwk (3H) but it does 
not cause the printer to perform a form advance. 

If the device specified by the calling routine is a metafile, 
v_clear_dispjist writes a metafile item to the metafile buffer. 

Input Arguments 

handle Device handle 



Sample Call to C Language Binding 

WORD v_clear_dispjist(); 
WORD handle; 

v_clear_dispjist{handle); 
Parameter Block Binding 

Control Input 

controllO) = 5 
control(l) = 
control(2) = 
controlO) = 
control(4) = 
control(5) = 22 
control(6) = handle 
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V_BITJMAGE (5-1 7H) 

v.bitjmage processes a bit image file (see Appendix G, "Bit Image File 
Format"). Input arguments include a filename and Information on 
image transformation and page placement. 

The calling routine provides three parameters to control image 
transformation: 

• pixel aspect ratio 

• X-axis scaling 

• Y~axis scaling 



Pixel Aspect Ratio 

The aspect flag allows the calling routine to specify whether the pixel 
aspect ratio defined in the bit Image file is to be preserved or ignored. 
Preserving pixel aspect ratio means the printed object will have the 
same aspect ratio it had on the device on which it was originally 
drawn; for example, squares remain squares, and circles remain circles. 
If the pixel aspect ration is ignored, the printed object will not 
necessarily have the same aspect ratio it had on the original device. 

Axis Scaling 

The two axis scaling flags can be set independently of each other. 
The scaling flags determine if the bit image's x or y axes are to be 
scaled fractionally or in integer multiples. The upward boundary of 
this scaling is a rectangle that the calling routine defines in the 
xyarray arguments. 

If an axis of the bit image is scaled fractionally, it will exactly fit the 
corresponding axis of the scaling rectangle, with the exception noted 
below. 

If an axis of the bit image is scaled in integer multiples. It might not 
exactly fit the corresponding axis of the scaling rectangle. 

If the scaled bit image does not exactly fit the scaling rectangle, the 
caller can use the h.align and v.align alignment parameters to locate 
the bit image within the rectangle. These parameters allow any 
combination of three vertical and three horizontal positions. 
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V.BITJMAGE (5-1 7H) 



Note: The scaled bit image always resides within the scaling 
rectangle. If a combination of preserved pixel aspect ratio, axis 
scaling, or alignment causes the scaled bit image to extend beyond an 
edge of the scaling rectangle, v.bitjmage clips the bit image to that 
edge. 

If the device specified by the calling routine Is a metafile, v_bitjmage 
writes a metafile item to the metafile buffer. 

Input Arguments 

handle Device handle 

filename Filename for bit image file. For the C language 

binding, this argument is byte-oriented and must be 
null-terminated. For the Parameter Block (assembly 
language) binding, the filename is word-oriented. 

aspect Aspect ratio flag: 

Ignore aspect ratio 

1 Honor pixel aspect ratio 

x_scale Scaling for x-axis: 

Fractional scaling 

1 Integer scaling 

y_scale Scaling for y-axis: 

Fractional scaling 

1 Integer scaling 



h_allgn 



Horizontal alignment: 



Left 

Center 

Right 
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v.aiign Vertical alignment: 

Top 

1 Middle 

2 Bottom 

xyarray[0] Upper left x (if specified) 

xyarray[1] Upper left y (if specified) 

xyarray[2] Lower right x (if specified) 

xyarray[3] Lower right y (if specified) 

Sample Call to C Language Binding 

WORD v.bitJmageO; 

BYTE *filename; 

WORD handle, aspect x_scale, y.scale, h_align, v_align, xyarray[l; 

v_bitjmage(handle, filename, aspect, x.scale, y_scale, h_align, 
v_align, xyarray); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 5 
control(l) = 2 
control(2) = 
controlO) = filename + 5 
control(4) = 
control(5) = 23 
controt(6) = handle 



intin(O) = aspect 
intin(l) = x_scale 
intin(2) = Y_scale 
intinO) = h_align 
intin(4) = v_align 
intin(5) 



lntin(n+4) = filename 
ptsin(O) = xyarraylOj 
ptsin(l) = xyarravlll 
ptsin(2) = xYarraY[2| 
ptsin(3) = xyarrayOI 
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VQ_SCAN (5-18H) 

vq.scan returns the height, In pixels, of a printer head pass and the 
number of head passes In a full page for both graphics and alpha 
modes. 

For devices in which the height of a single head pass is not a discrete 
number of pixels, this function returns a division factor. For example, 
if the device outputs 12.5 pixels in a single alpha pass and 4 pixels in 
a single graphics pass, vq.scan returns an alpha scan height of 25, a 
graphics scan height of 8, and a division factor of 2. 

Input Arguments 

handle Device handle 



Output Arguments 

g_height Graphics scan height in scaled pixels 

g_slices Number of graphics head passes per page 

a.height Alpha scan height in scaled pixels 

a.slices Number of alpha head passes per page 

factor Scan height division factor 

Sample Call to C Language Binding 

WORD vq_scan(); 

WORD handle, g_height, g_sllces, a_height, a_slices, factor; 

vq_scan(handle, 8tg_height, 8tg_slices, 8ta_height, 8ia_slices, &factor; 
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Parameter Block Binding 

Control Input 



Output 



control(O) = 5 
control(l) = 
control(2) = 
controlO) = 
ccntrol(4) = 5 
controKS) = 24 
control(6) = handle 



intout(O) = g_height 
intout(l) = g-slices 
intout(2) = a_height 
IntoutO) = a_slices 
intout(4) = factor 
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V_ALPHA_TEXT (5-19H) 

v_alpha_text outputs a specified string of alpha text to the printer. 
You must load a font before calling this function; see vstjoadjonts 
(77H) in Section 3. v_alpha_text is required only for printers. 

The alpha text string is output at the current printer head position. All 
characters are output exactly as specified, with the following 
exceptions: 

• The form-feed character (ADE value 12) has the same effect as a 
v_form_advance (5-14H) call. 

• The two-character control sequences listed below invoke the 
described printer functions, if supported. DC2 refers to ADE value 
18. 



(DC2)0 


— Begin boldface 


(DC2)1 


— End boldface 


(DC2)2 


— Begin italics 


(DC2)3 


— End italics 


(DC2)4 


— Begin underscore 


(DC2)5 


— End underscore 


Input Arquments 


handle 


Device handle 


string 


ASCII character string 



For the C language bindings, the string Is byte- 
oriented and must be null terminated. For the 
Parameter Block (assembly) bindings, the string is 
word-oriented. work_out[15l of vq_extnd (66H) 
returns the maximum number of characters (size of 
intin array) allowed in the string. vq.extnd is 
described in Section 8. 
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Sample Call to C Langua g e Bind ing 

WORD v_alpha_text(); 
WORD handle; 
BYTE *strlng; 

v_alpha_text(handle, string); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin = string 

control(l) = 

control(2) = 

control(3) = number of chars 

in string 

control(4) = 

controKS) = 25 

ccntrol(6) = handle 
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VS_PALETTE (5-3CH) 

This function allows the calling routine to select a color palette on the 
IBM® medium-resolution color screen. vs_palette returns the selected 
palette. 

Input Arguments 

handle Device handle 

palette Color selection: 

Use red, green, brown palette (default) 

1 Use cyan, magenta, white palette 

Output Arguments 

selected Selected palette 

Sample all C Language Binding 

WORD vs_palette(); 
WORD handle, palette; 

selected = vs_palette(handle, palette); 
Parameter Block Bindin g 

Control Input Output 

control(O) = 5 intln(O) = palette Intout(O) = selected 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 1 

controMS) = 60 

control(6) = handle 



9-33 



V.SOUND (5-3DH) GEM VDI Reference Guide 

V_SOUND (5-3DH) 

v_sound generates a tone of the specified frequency for the specified 
time interval. 

Tone generation can be suppressed with vs_mute (5-3EH); see page 
9-35. 



Input Arguments 

handle Device handle 

frequency Tone frequency in hertz 
duration Tone duration in timer ticks 

Sample Call to C Language Binding 

WORD v_sound(); 

WORD handle, frequency, duration; 

v_sound(handle, frequency, duration); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = frequency 

control(l) = intind) = duration 

control(2) = 

controlO) = 2 

control(4) = 

controi(5) = 61 

control(6) = handle 
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VS_MUTE (5-3EH) 

vs_mute sets, clears, or returns the current state of the muting flag. 
The muting flag controls tone generation. 

Input Arguments 

handle Device handle 

action Action to perform: 

-1 Return state of muting flag 

Enable tone generation 

1 Disable tone generation 

Output Arguments 

status Current state of muting flag (undefined for enable 

and disable calls): 

zero Tone generation enabled 

nonzero Tone generation disabled 

Sample Call to C Language Binding 

WORD vs_mute(); 
WORD handle.action; 

status = vs_mute(handle,action); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = action intout(O) - status 

controllD = 
control(2) = 
controlO) = 1 
control{4) = for set 

1 for Inquire 
control(5) = 62 
control(6) = handle 
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VT.RESOLUTION (5-51 H) 

This function sets the x and y resolution of the tablet. Resolution is 
specified independently for each axis in units of lines per inch, 
vt.resolution performs upper limit range checking on the xres and yres 
input arguments and returns the actual resolutions set. 

Input Arguments 

handle Device handle 

xres Tablet x resolution in lines/inch 

yres Tablet y resolution in lines/inch 

Output Arguments 

xset Actual x resolution set 

yset Actual y resolution set 

Sample Call to C Language Binding 

WORD vt_resolutlon(); 

WORD handle, xres, yres, xset, yset; 

vt_resolutlon(handle, xres, yres, 8(xset, &yset); 



Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = xres intout(O) = xset 

control(l) = intin(l) = yset intout(l) = yset 

control(2) = 

controlO) = 2 

control(4) = 2 

control(5) = 81 

control(6) = handle 
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VT_AXIS (5-52H) 

vt.axis sets the x and y axis resolution of the tablet. Resolution is 
specified independently for each axis in units of lines per axis. Since 
the resolution of the tablet must ultimately be expressed as an integral 
number of lines per inch, this vt.axis returns the actual axis resolution 
realized. 



Input Arguments 

handle Device handle 

xres Tablet x resolution in lines 

yres Tablet y resolution in lines 

Output Arguments 

xset Actual x resolution set 

yset Actual y resolution set 

Sample Call to C Language Binding 

WORD vt_axis(); 

WORD handle, xres, yres, xset, yset; 

vt_axis{ handle, xres, yres, 8»xset, 8»yset); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 , intln(O) = xres intout(O) = xset 

control(l) = intin(l) = yres Intout(l) = yset 

control(2) = 

controlO) = 2 

control(4) = 2 

control(5) = 82 

control(6) = handle 
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VT^ORGIN (5-53H) 

This function sets the x and y origin of the tablet. 



input Arguments 

handle Device handle 

xorigin 



yongin 



x-coordinate of upper left corner of tablet origin in 
lines (tablet units) 

y-coordinate of upper left corner of tablet origin in 
lines (tablet units) 



Sample Call to C Language Binding 

WORD vt_origin(); 

WORD handle, xorigin, yorigin; 

vt_origin(handle, xorigin, yorigin); 



Parameter Block Binding 

Control Input 



Output 



control(O) = 5 
control(l) = 
control(2) = 
controlO) = 2 
control(4) = 
controKS) = 83 
control(6) = handle 



intin(O) = xorigin 
intin(l) = yorigin 
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VQ.TDIMENSIONS (5-54H) 

This function returns the x and y dimensions of the tablet in tenths of 
inches. 



Input Arguments 

handle Device handle 

Output Arguments 

xdimension Tablet x dimension in tenths of inches 
ydimension Tablet y dimension in tenths of inches 

Sample Call to C Language Binding 

WORD vq_tdimensions(); 

WORD handle, xdimension, ydimension; 

vq_tdimensions(handle, &xdimension, &ydimension); 
Parameter Block Binding 

Control Input ' Output 

controMO) = 5 mtout(O) = xdimension 

control(l) = intout(l) = ydimension 

control(2) = 

controlO) = 

controi(4) = 2 

control(5) = 84 

control(6) = handle 
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VT^ALIGNMENT (5-55H) 

This function establishes an alignment between the physical coordinate 
axes of the tablet and the coordinate axes of, for example, a drawing 
affixed to the tablet surface. 

vt.alignment Is intended to account for. inaccurate registration of a 
drawing with the physical coordinate axes, and might be used prior to 
tracing a drawing. 

The input arguments are delta_x (dx) and deita.y (dy), which are the 
signed lengths of the sides of a triangle whose hypotenuse lies along 
the desired x or y axis of the drawing. If the hypotenuse of the 
triangle is defined by two points [x1, y1] and [x2, y2], delta.x is defined 
as (x2 - x1), while delta.y Is defined as (y2 - y1). 

Input Arguments 

handle Device handle 

dx Signed length of the x component of a triangle 

whose hypotenuse lies along the intended x or y axis 

dy Signed length of the y component of a triangle 

whose hypotenuse lies along the intended x or y axis 

Sample Call to C Language Binding 

WORD vt_alignment(); 
WORD handle, dx, dy; 

vt_alignment(handle, dx, dy); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intln(O) = dx 

control(l) = Intinn) = dy 

control{2) = 

controlO) = 2 

control(4) = 

controKS) = 85 

control(6) = handle 
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VSP_FILM (5-5BH) 

vsp_film selects the film type and exposure time. 

Input Arguments 

handle Device handle 

index Desired film type index number from 1 - n where n 

is the maximum available 

Use vqpjilmname (5-5CH) to obtain the name of the 
film associated with an index. 

lightness Lightness integer from -3 and 3. Each integer 

increase represents opening the aperture 1/3 of an f- 
stop. That is, -3 results in an exposure one half 
normal; 3 results in an exposure double normal. 

Sample Call to C Language Bindin g 

WORD vsfilmO; 

WORD handle, index, lightness; 

vsp_fiim(handle, index, lightness); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = index 

control(l) = intin(l) = lightness 

control(2) = 

controlO) = 2 

control(4) = 

control(5) = 91 

control(6) = handle 
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VQP^FILMNAME (5-5CH) 

This function returns the film name for the element specified by the 
calling routine, vqpjilmname returns the film name as a string up to 
24 characters long, null terminated. If the specified element number 
(the index argument) is invalid, a null string is returned (control(4) is 
zero). 

Input Arguments 

handle Device handle 

index Requested element number 

Output Arguments 

status .TRUE. If contrl[4] 1= 

.FALSE, if contrl[4l == 

name Film name (ADE values), word-oriented for Parameter 

Block (assembly language) bindings, byte-oriented for 
C language binding 

Sample Call to C Language Binding 

BOOLEAN vqpJilmnameO; 
BOOLEAN status; 
WORD handle, index; 
BYTE name[25] 

status = vqp_filmname(handle, index, name); 
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VQP.FILMNAME (5-5CH) 



Parameter Block Binding 

Control Input 



Output 



control(O) = 5 
control(l) = 
controt(2) = 
controlO) = 1 
control(4) = number of chars 

in intout 
controKS) = 92 
control(6) = handle 



intin(O) = index 



intout = name 
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VSC_EXPOSE (5-5DH) 

vsc.expose disables or enables the film exposure on some camera- 
type devices so that you can preview the frame prior to exposure. 
This function is limited to devices that support the preview capability. 

Input Arguments 

handle Device handle 

state Exposure state set as follows: 

zero Disable exposure 

nonzero Enable exposure 

Sample Call to C Language Binding 

WORD vsc_expose(); 
WORD handle, state; 

vsc_expose(handle, state); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = state 

control(l) = 

control(2) = 

controlO) = 1 

control(4) = 

controKB) = 93 

control(6) = handle 



9-44 



GEM VDI Reference Guide V.META.EXTENTS (5-62H) 

V_META_EXTENTS (5-62H) 

v_meta_extents uses the values specified by the calling routine to 
update the extents Information in the metafile header. The extents 
information can be used as a quick indication of the minimum 
rectangle that will bound all primitives output to the metafile. See 
Appendix B for a description of the metafile header and "Special 
Metafile Escapes." 

If extent values are not defined when outputting to the metafile.all four 
bounding values default to zero. 

Input Arguments 

handle Device handle 

min_x Minimum x value of the minimum bounding rectangle 

min_Y Minimum y value of the minimum bounding rectangle 

maxj( Maximum x value of the minimum bounding rectangle 

max_y Maximum y value of the minimum bounding rectangle 

Sample Call to C Language Binding 

WORD v_meta_extents{); 

WORD handle, min_x, min.y, max_x, max_y; 

v_meta_extents(handle, min_x, min_y, max_x, max_y); 
Parameter Block Binding 

Control Input 

control(O) = 5 ptsin(O) = min_x 

control(l) = 2 ptsin(l) = min_y 

control(2) = ptsm(2) = max_x 

controlO) = ptsin(3) = max_v 

control(4) = 
controKS) = 98 
control(6) = handle 
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V_WRITE_META (5-63H) 

v_write_meta writes the intin and ptsin parameters to the metafile. 
The first word of the intin array should contain a sub-opcode that 
defines this information as a user-defined metafile item. 

The VDI reserves sub-opcodes through 100. The sub-opcode you 
use to define your metafile item must be numbered 101 or higher. 

Input Arguments 

handle Device handle 

numjntin Length of intin array 
numjstsin Number of input vertices 
intin User-defined information 

ptsin User-defined information 

Sample Call of C Language Binding 

WORD v_write_meta(); 

WORD handle, numjntin, num_ptsin, intin[numjntinl, 
ptsin[num_ptsin]; 

v_write_meta(handle, numjntin, intin, num_ptsin, ptsin); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 intin(O) = sub-opcode 

control(l) = num_ptsin intin = intin 

control(2) = 

controi(3) = numjntin ptsin = ptsin 

control(4) = 

control|5) = 99 

control(6) = handle 
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VM.FILENAME (5-64H) 

When a metafile is first opened, its default name is GEMFILE.GEM and 
its default location is the current drive and directory. vm_filename 
renames a metafile from GEMFILE.GEIVI to the name specified by the 
calling routine. The metafile extension of GEM is maintained. The 
specified name can include a path and drive to locate the file 
somewhere other than on the current drive and directory. 

Note: Call this function immediately after opening the metafile (see 
v_opnwk (1H) in Section 3) or it has no effect, vmjilename closes and 
deletes any open metafiles. Before this function is invoked, all 
metafile output is directed to GEMFILE.GEM. 

Input Arguments 

handle Device handle 

filename Path/filename (null-terminated for C binding) 

Sample Call to C Language Binding 

WORD vm_filename; 
WORD handle; 
BYTE *filename; 

vm_filename(handle, filename); 
Parameter Block Binding 

Control Input Output 

control(O) = 5 lntin|0 to n) = filename. 

control(l) = 

control(2) = 

control(3) = number of chars 

in filename 
control(4) = 
controKS) = 100 
control(6) = handle 



End of Section 9 
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Command line syntax error 

Description: The VDI displays this message when the command 
line includes an illegal character, path, or drive 
specification. 

Solution: Be sure that the command line conforms the 

operating system's command line conventions. 
Reenter the command line after correcting illegal 
entries. 

Unable to find ASSIGN.SYS 

Description: This message indicates that the VDI is unable to find 
the ASSIGN.SYS file in the specified location. 

Solution: Place the ASSIGN.SYS file in the current directory. 

Error reading ASSIGN.SYS 

Description: The VDI cannot use the ASSIGN.SYS file because its 
format is Incorrect. 

Solution: Refer to Section 1 for the file's correct format. 

Memory table corrupted 

Description: This message indicates that the system's memory is 
corrupted. 

Solution: Reboot your system. 
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Insufficient memory 

Description: This message indicates that the VDI cannot satisfy 
your memory allocation request. 

Solution: If your system has enough memory to run the VDI, 

reboot your system. 

Invalid memory block address 

Description: This message indicates that the system's memory is 
corrupted. 

Solution: Reboot the system. 

Drive specification not allowed in ASSIGN.SYS 

Description: This message indicates that your ASSIGN.SYS file 
contains an illegal drive specification. 

Solution: Edit the file to remove the drive specification. The 

correct format of an ASSIGN.SYS file is described in 
Section 1. 

illegal device id in ASSIGN.SYS 

Description: The VDI displays this message when your 
ASSIGN.SYS file contains a device ID number that 
exceeds the range of values listed in Table 1-1. 

Solution: Refer to Table 1-1 in Section 1 for the valid device 

ID numbers. Correct the ASSIGN.SYS file with your 
text editor. 

Partial record found in ASSIGN.SYS 

Description: This message indicates that your ASSIGN.SYS file 
contains a partial entry. 

Solution: Check your ASSIGN.SYS file for incomplete device ID 

numbers or filenames. Refer to Section 1 for the 
correct ASSIGN.SYS file format. 
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Invalid filename encountered in ASSIGN.SYS 

Description: Your ASSIGN.SYS file contains a filename which Is 
either too long or contains illegal characters. 

Solution: Locate the invalid filename within ASSIGN.SYS and 

correct it using the following guidelines: 

• The filename must have eight or fewer 
characters. 

• The first character in the filename must be 
alphabetic. 

• The file's extension must be SYS. 

ASSIGN.SYS file is empty 

Description: The VDI displays this message to indicate that it has 
found an empty ASSIGN.SYS file. 

Solution: Use your text editor to enter the necessary 

ASSIGN.SYS information. Section 1 describes the 
ASSIGN.SYS contents. 

Corrupted driver file 

Description: When the VDI has found, but is unable to use, a 
device driver specified in ASSIGN.SYS, it displays this 
message. 

Solution: Use your distribution disk to make another copy of 

the device driver. Try to use the new copy. Contact 
your dealer if you are unable to use the device 
driver. 



End of Appendix A 
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GEM VDI Metafile Format 



This appendix describes the information output by the metafile driver 
and the operations it performs for various VDI functions. 

Standard Metafile Item Format 



Most of the function requests passed to the metafile driver result in 
the driver writing a standard metafile item to the metafile buffer. In a 
standard format metafile item, the control, integer, and vertex 
parameters are written to the metafile in the format shown in Table 
B-1. 



Table B-1. Control, Integer and Vertex Parameters 



Word 



Value 



Description 






control[0] 


opcode 


1 


control[11 


vertex count 


2 


control[3] 


integer parameter count 


3 


control[5] 


sub-opcode (or zero) 


4... 


ptsin[0-n] 


input vertices (if provided) 


n+4... 


intin[0-ml 


input integer (if provided) 



Note if the vertex or integer parameter count is zero, nothing is output 
for the ptsin or intin information. 
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Standard Metafile Function Req uests 

Requests for the functions listed below cause the metafile driver to 
output a standard metafile item. 

Opcode (Decimal) Function 

3 Clear Workstation, v_clrwk (3H) 

4 Update Workstation, v_updwk (4H) 
5-2 Exit Alpha Mode, v.exltcur (5-2H) 
5-3 Enter Alpha Mode, v_entercur (5-3H) 
5-20 Form Advance, v_form_adv (5-14H) 

5-21 Output Window, v_output_wlndow (5-15H) 

5-22 Clear Display List, v_clear_dispjist (5-16H) 

5-23 Output Bit Image File, v_bitjmage (5-17H) 

5-25 Output Printer Alpha Text, v_alpha_text (5-19H) 

6 Polyline, vjine (6H) 

7 Polymarker, v_pmarker (7H) 

8 Text, v_qtext (8H) 

9 Fill Area, vjillarea (9H) 
11-1 Bar GDP, v_bar (B-1H) 
11-2 Arc GDP, v.arc (B-2H) 
11-3 Pie GDP, v_pieslice (B-3H) 
11-4 Circle GDP, v.circle (B-4H) 
11-5 Ellipse GDP, v.ellipse (B-5H) 
11-6 Elliptical Arc GDP, v.ellarc (B-6H) 
11-7 Elliptical Pie Slice GDP, v.ellpie (B-7H) 
11-8 Rounded Rectangle GDP, v_rbox (B-8H) 

11-9 Filled, Rounded Rectangle GDP, v.rfbox (B-9H) 

11-10 Justified Graphics Text GDP, vjustified (B-AH) 

12 Set Character Height, Absolute Mode, vst_height (C 

13 Set Character Baseline Vector, vst_rotatlon (DH) 

14 Set Color Representation, vs_color (EH) 

15 Set Polyline Line Type, vsljype (FH) 

16 Set Polyline Line Width, vsLwidth (lOH) 

17 Set Polyline Color Index, vsl.color (IIH) 

18 Set Polymarker Type, vsm_type (12H) 

19 Set Polymarker Height, vsm_helght (13H) 

20 Set Polymarker Color Index, vsm_color (14H) 

21 Set Text Font, vstjont (15H) 

22 Set Text Color Index, vst.color (16H) 
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23 Set Fill Interior Style, vsfjnterior (17H) 

24 Set Fill Style Index, vsf .style (18H) 

25 Set Fill Color Index, vsf_color (19H) 
32 Set Writing Mode, vswr.mode (20H) 

39 Set Graphic Text Alignment, vst_alignment (27H) 

104 Set Fill Perimeter Visibility, vsf .perimeter (68H) 

106 Set Graphic Text Special Effects, vst.effects (6AH) 

107 Set Character Height, Points Mode, vstj)oint {6BH) 

108 Set Polyline End Styles, vsi.ends (6CH) 

112 Set User-defined Fill Pattern, vsf.udpat (70H) 

113 Set User-defined Line Style Pattern, vsl.udsty (71H) 

114 Fill Rectangle, vr.recfl (72H) 

129 Set Clipping Rectangle, vs.cllp (81 H) 
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Nonstandard Metafile Items 



Open Workstation - v_opnwk (1H) 

v.opnwk initializes the metafile buffer and writes the metafile header 
to it. The device values normally returned by v_opnwk are returned. 
The format of the metafile header is described below. 

Metafile Header Format 

Word Description 

Offffh 

1 Length of header in words 

2 100*major version number + minor version number 

3 NDC/RC transformation mode flag: 

positive y values ascend from origin (origin in 
lower left corner) 

2 positive y values descend from origin (origin in 
upper left corner) 

4-7 Minimum and maximum x and y extent values for the 

information contained in the metafile. If undefined by 
the application (see v_meta_extents (5-62H) in 
Section 9), all four values are zero. The values are 
stored in the following order: minimum x, minimum 
y, maximum x, maximum y. 

8-9 Physical page size: page width in tenths of 

millimeters, followed by page height in tenths of 
millimeters. If undefined by the application, both 
values are zero. (See Appendix C, "Reserved Metafile 
Sub-opcodes.") 



B-4 



GEM VDI Reference Guide Nonstandard Metafile items 



Word Description 

10 - 13 The coordinate window whiich defines the coordinate 

system used in the metafile. If undefined by the 
application, all four values are zero. The values are 
stored in the following order: lower left x, lower left 
y, upper right x, upper right y. (See Appendix C.) 

14 Bit image opcode flag: 

No bit image opcode in file 

1 Bit image opcode included in metafile 

Bits 1-15 must be zero. 



Close Workstation - v-.clswk (2H) 

v_clswk appends an end-of-metaflle marker, OFFFFH (one word) to the 
metafile buffer. It then flushes the buffer and closes the metafile. 
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Special Metafile Escapes 

There are three escape functions that provide special functions for 
metafiles. These functions are briefly described here; Section 9 
provides more detailed information. 



Update Metafile Extents - v-.meta_extents (5-62H) 

v_meta_extents updates words 4 - 7 in the metafile header to indicate 
the extents passed in the ptsin array. 



Write Metafile Item - v,write.,meta (5-63H) 

v.write.meta v\^rites the intin and ptsin parameters to the metafile. 
The first word of the intin array should contain a sub-opcode that 
defines what type of user-defined metafile item is being written. This 
special sub-opcode can be used by an application to identify the 
metafile item when it is read in. The VDI reserves sub-opcodes 
through 100. 



Change GEM VDI Filename - vm-fiiename (5-64H) 

if any information currently exists in the metafile or metafile buffer, 
vmjilename flushes the buffer and closes the file, vmjilename 
reinitializes the metafile buffer and performs rudimentary file name 
validation. If the drive, path, and filename are valid, they are used to 
update the File Control Block (FCB) of the metafile. The metafile will 
not actually be opened until the first buffer needs to be flushed. 
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Inquire Functions 



Inquire Addressable Character Cells - vq-chcelis (5-1 H) 

vq_chcells returns -1 in both intout(O), rows, and intout(l), columns, to 
indicate that cursor addressing is not possible. 



Inquire Color Representation - vq-color (1AH) 

vq_color returns -1 for the color index to indicate that no value Is 
available. 



Inquire Current Polyline Attributes - vqLattributes (23H) 
vqLattributes returns the set values. 

Extended Inquire - vq-extnd (66H) 

vq.extnd returns the appropriate inquiry values. 



End of Appendix B 
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Reserved Metafile Sub-opcodes 



This appendix describes the metafile sub-opcodes reserved for two 
Digital Research GEM applications, GEM Output^"^ and GEM Draw"'^'^. 



Metafile Sub-opcodes for GEM Output 

The VDI reserves two sub-opcodes for sub-functions used by the GEM 
Output application: 

Sub-opcode Sub-function 

Physical Page Size — Defines how large a picture is 
to be rendered on the output page. 

1 Coordinate Window — Defines a newpage 
transformation which maps from the metafile 
coordinate system to the output device. 

The two GEM Output metafile sub-opcodes result in an update of the 
metafile header. The opcodes are not actually written to the body of 
the metafile. 
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Physical Page Size 

This sub-function defines the size of the output area. All of the data 
in the coordinate window is mapped to this area. If no physical page 
size is defined, the Output application will attempt a best fit on the 
target device, assuming that "pixels" in the metafile are square. 

Input Arguments 



control(O) 


5 


control(l) 





control(3) 


3 


control(5) 


99 


control(6) 


Device handle 


intin(O) 


Sub-opcode number, 


intin(l) 


Page width, in tenths of millimeter 


intin(2) 


Page height. In tenths of millimeter 


Output Arguments 


control(2) 





control(4) 
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Coordinate Window 

This sub-function defines the coordinate system used in the metafile. 
All of the data in the defined coordinate window is mapped to the area 
defined by the Physical Page Size sub-function. 

The coordinate window defaults to NDC space (0 to 32K). The location 
of the origin (0, 0), depends on the coordinate space set when the 
metafile was opened; see v_opnwk (1H) In Section 3. For example, if 
raster coordinate space was specified when v.opnwk was invoked, the 
origin would be located in the upper left corner of the display surface. 

Note that the window corner information must be specified as the 
lower left and upper right corners. Arbitrary opposing corners will not 
convey enough information. 

Input Arguments 



control(O) 


5 


control(l) 





control(3) 


5 


control(5) 


99 


control(6) 


Device handle 


intin(O) 


Sub-opcode, 1 


intin(l) 


x-coordinate of lower left corner of window 


intin(2) 


y-coordlnate of lower left corner of window 


intin(3) 


x-coordinate of upper right corner of window 


lntin(4) 


y-coordinate of upper right corner of window 


Output Arguments 


control(2) 





control(4) 
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Metafile Sub-opcodes for GEM Draw 

The following sub-opcodes are reserved for use by the GEM Draw 
application. GEM VDI defines the sub-opcodes for the following sub- 
functions: 



Sub-opcode 


Sub-function 


10 


Group 


49 


Set No Line Style 


50 


Set Attribute Shadow On 


51 


Set Attribute Shadow Off 


80 


Start Draw Area Type Primitive 


81 


End Draw Area Type Primitive 
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Group 

This sub-function indicates how many previous primitives are grouped. 
The number of preceding primitives in the group is passed to the sub- 
function in intin(1). 

Input Arguments 



control(O) 


5 


control(l) 





control(3) 


2 


controi(5) 


99 


control(6) 


Device handle 


intin(O) 


Sub-opcode number, 10 


intin(l) 


Number of preceding GEIVI Draw primitives in the 




group 


Output Arguments 


control(2) 





controi(4) 
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Set No Line Style 

This sub-function is used by GEIVI Draw to indicate that subsequent 
area type primitives are not to be outlined. The effects of this sub- 
opcode are cancelled by any subsequent calls to vsLtype (FH); see 
Section 5. 



Input Arguments 

control(O) 5 

control(l) 

control(3) 1 

control(5) 99 

control(6) Device handle 

intin(O) Sub-opcode number, 49 



Output Arguments 

control(2) 
control(4) 
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Set Attribute Shadow On 

This sub-function is used by GEM Draw to indicate that ail subsequent 
primitives that occur before the next Set Attribute Shadow Off sub- 
function should be ignored. This is because such primitives are used 
to draw a drop shadow for the first primitive immediately following the 
Set Attribute Shadow Off call. 

Internally, GEM Draw assigns a shadowed attribute to the first 
primitive that follows the Set Attribute Shadow Off call and performs 
its own shadow drawing. All attribute information which occurs 
between Set Attribute Shadow On and Set Attribute Shadow Off will 
continue to be processed. 

Note that GEM Draw will not drop shadows from text or from polylines 
consisting of only two vertices. 

Input Arguments 

control(O) 5 

control(l) 

control{3) 1 

control(5) 99 

control(6) Device handle 

intin(O) Sub-opcode number, 50 

Output Arguments 

control(2) 
control(4) 
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Set Attribute Shadow Off 

This sub-function Indicates to GEM Draw the end of primitives used to 
draw a drop shadow of the first primitive immediately following this 
sub-opcode. 

Input Arguments 

control(O) 5 

controlil) 

control(3) 1 

control(5) 99 

control(6) Device handle 

intin(O) Sub-opcode number, 51 

Output Arguments 

control(2) 
control(4) 



C-8 



GEM VDI Reference Guide Start Draw Area Type Primitive 

Start Draw Area Type Primitive 

This sub-function indicates to GEIVI Draw that an area type primitive 
biocic follows. GEI\/I Draw will use the vertices of the first primitive 
(anything except text) that follows this sub-opcode to define a GEM 
Draw area type primitive. 

All other primitives encountered before the next End Draw Area Type 
Primitive sub-opcode will be ignored. 

Input Arguments 

control(O) 5 

control(l) 

control(3) 1 

control(5) 99 

control(6) Device handle 

intin(O) Sub-opcode number, 80 

Output Arguments 

control(2) 
control(4) 
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End Draw Area Type Primitive 

This sub-function indicates the end of an area type primitive blocic to 
GEM Draw. 



input Arguments 

control(O) 5 

control(l) 

control(3) 1 

control(5) 99 

control(6) Device handle 

intin(O) Sub-opcode number, 81 



Output Arguments 

control(2) 
control(4) 



End of Appendix C 



C-10 



Appendix D 



Standard Keyboard 



The VDI defines a standard iceyboard so applications can taice 
advantage of special iceys not defined In the standard, 7-bit ASCII 
character set. A 16-bit value is used to return these characters. The 
high byte contains a binary value assigned to each key. The low byte 
contains the 7-bit ASCII vafue, if such a value Is defined, or a zero If 
the code Is an extended code. 



Table D-1. GEM VDI Standard Keyboard Assignments 



High Byte 


Low Byte 


Character 


03 


00 


CNTL 2 (Nul) 


IE 


01 


CNTL A 


30 


02 


CNTL B 


2E 


03 


CNTLC 


20 


04 


CNTL D 


12 


05 


CNTL E 


21 


06 


CNTL F 


22 


07 


CNTL G 


23 


08 


CNTL H 


17 


09 


CNTL 1 


24 


OA 


CNTL J 


25 


OB 


CNTL K 


26 


OC 


CNTL L 


32 


OD • 


CNTL M 


31 


OE 


CNTL N 


18 


OF 


CNTL 


19 


10 


CNTL P 


10 


11 


CNTL Q 


13 


12 


CNTL R 


IF 


13 


CNTL S 


14 


14 


CNTL T 


16 


15 


CNTL U 



D-1 



Standard Keyboard GEM VDI Reference Guide 





Table D-1. 


(Cont'd) 


High Byte 


Low Byte 


Character 


2F 


16 


CNTL V 


11 


17 


CNTL W 


2D 


18 


CNTL X 


15 


19 


CNTL Y 


2C 


1A 


CNTLZ 


1A 


IB 


CNTL[ 


2B 


1C 


CNTL W 


IB 


ID 


CNTL ] 


07 


IE 


CNTL 6 


OC 


IF 


CNTL - 


39 


20 


Space 


02 


21 


! 


28 


22 


» 


04 


23 


# 


05 


24 


$ 


06 


25 


% 


08 


26 


8i 


28 


27 


/ 


OA 


28 


( 


OB 


29 


) 


09 


2A 


* 


OD 


2B 


+ 


33 


2C 


^ 


OC 


2D 


- 


34 


2E 




35 


2F 


/ 


OB 


30 





02 


31 


1 


03 


32 


2 


04 


33 


3 


05 


34 


4 


06 


35 


5 


07 


36 


6 


08 


37 


7 


09 


38 


8 



D-2 



GEM VDI Reference Guide 


1 




Standard Keyboard 




Table D-1. 


(Cont'd) 




High Byte 


Low Byte 




Character 



OA 

27 

27 

33 

OD 

34 

35 

03 

IE 

30 

2E 

20 

12 

21 

22 

23 

17 

24 

25 

26 

32 

31 

18 

19 

10 

13 

IF 

14 

16 

2F 

11 

2D 

15 



39 


9 


3A 


; 


38 


» 


3C 


< 


3D 


= 


3E 


> 


3F 


? 


40 


@ 


41 


A 


42 


8 


43 


C 


44 


D 


45 


E 


46 


F 


47 


G 


48 . 


H 


49 


1 


4A 


J 


48 


K 


4C 


L 


4D 


M 


4E 


N 


4F 





50 


P 


51 


Q 


52 


R 


53 


S 


54 


T 


55 


U 


56 


V 


57 


w 


58 


X 


59 


Y 
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Table D-1. (Cont'd) 

High Byte Low Byte Character 

2C 

1A 

2B 

IB 

07 

OC 

29 

IE 

30 

2E 

20 

12 

21 

22 

23 

17 

24 

25 

26 

32 

31 

18 

19 

10 

13 

IF 

14 

16 

2F 

11 

2D 

15 

2C 



5A 


Z 


5B 


[ 


5C 


w 


5D 


1 


5E 


/\ 


5F 


_ (Underscore) 


60 


I 


61 


a 


62 


b 


63 


c 


64 


d 


65 


e 


66 


f 


67 


g 


68 


h 


69 


i 


6A 


i 


6B 


k 


6C 


1 


6D 


m 


6E 


n 


6F 


o 


70 


P 


71 


q 


72 


r 


73 


s 


74 


t 


75 


u 


76 


V 


77 


w 


78 


X 


79 


Y 


7A 


z 



D-4 



GEM VDI Reference Guide 






Standard Keyboard 




Fable D-1. 


(Cont'd) 




High Byte 


Low Byte 




Character 



lA 

2B 

IB 

29 

OE 

81 

78 

79 

7A 

7B 

7B 

7D 

7E 

7F 

80 

IE 

30 

2E 

20 

12 

21 

22 

23 

17 

24 

25 

26 

32 

31 

18 

19 

10 

13 

IF 



78 


{ 


7C 


1 


7D 


} 


7E 


- 


7F 


Rubout (DEL) 


00 


Alto 


00 


Alt 1 


00 


Alt 2 


00 


Alt 3 


00 


Alt 4 


00 


Alt 5 


00 


Alt 6 


00 


Alt 7 


00 


Alt 8 


00 


Alt 9 


00 


Alt A 


00 


Alt B 


00 


Alt C 


00 


Alt D 


00 


Alt E 


00 


Alt F 


00 


Alt G 


00 


Alt H 


00 


Alt i 


00 


Alt J 


00 


Alt K 


00 


Alt L 


00 


Alt M 


00 


Alt N 


00 


Alt 


00 


Alt P 


00 


Alt Q 


00 


Alt R 


00 


Alt S 
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Table D-1. 


(Cont'd) 




High Byte 


Low Byte 


Character 




14 


00 


Alt T 




16 


00 


Alt U 




2F 


00 


Alt V 




11 


00 


Alt W 




2D 


00 


Alt X 




15 


00 


Alt Y 




2C 


00 


Alt Z 




3B 


00 


F1 




3C 


00 


F2 




3D 


00 


F3 




3E 


00 


F4 




3F 


00 


F5 




40 


00 


F6 




41 


00 


F7 




42 


00 


F8 




43 


00 


F9 




44 


00 


F10 




54 


00 


F11 




55 


00 


F12 




56 


00 


F13 




57 


00 


F14 




58 


00 


F15 




59 


00 


F16 




5A 


00 


F17 




58 


00 


F18 




5C 


00 


F19 




5D 


00 


F20 




5E 


00 


F21 




5F 


00 


F22 




60 


00 


F23 




61 


00 


F24 




62 


00 


F25 




63 


00 


F26 




64 


00 


F27 
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High Byte Low Byte Character 



65 

66 

67 

68 

69 

6A 

6B 

6C 

6D 

6E 

6F 

70 

71 

73 

4D 

4D 

74 

50 

50 

48 

48 

51 

51 

76 

49 

49 

84 

77 

47 

47 

52 

52 

53 

53 



00 


F28 


00 


F29 


00 


F30 


00 


F31 


00 


F32 


00 


F33 


00 


F34 


00 


F35 


00 


F36 


00 


F37 


00 


F38 


00 


F39 


00 


F40 


00 


Ctrl left-arrow 


00 


right-arrow 


36 


Shift right-arrow 


00 


Ctrl right-arrow 


00 


down-arrow 


32 


Shift down-arrow 


00 


up-arrow 


38 


Shift up-arrow 


00 


Page down 


33 


Shift Page down 


00 


Ctrl Page down 


00 


Page up 


39 


Shift Page up 


00 


Ctrl Page up 


00 


Ctrl Home 


00 


Home 


37 


Shift Home 


00 


Insert 


30 


Shift Insert 


00 


Delete 


2E 


Shift Delete 
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Table D-1. 


(Cont'd) 


High Byte 


Low Byte 


Character 


72 


00 


Ctrl Print Screen 


37 


2A 


Print Screen 


01 


IB 


Escape 


OE 


08 


Backspace 


82 


00 


Alt - 


83 


00 


Alt = 


1C 


OD 


CR 


IC 


OA 


Ctrl CR 


4C 


35 


Shift Num Pad 5 


4A 


2D 


Num Pad - 


4E 


2B 


Num Pad + 


OF 


09 


Tab 


OF 


00 


Backtab 


4B 


00 


left-arrow 


48 


34 


Shift left-arrow 


4F 


00 


End 


4F 


31 


Shift End 


75 


00 


Ctrl End 



End of Appendix D 
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Processor-Specific Data 



8086-Specific Data 

Registers and Interrupts 

The application program passes the address of the Parameter Block to 
GEM VDI in registers DS:DX. Pass the VDI ID number, 1139 (0473H), In 
the register CX. The interrupt is EF. 

Note: GEM VDI runs on Concurrent^*^ operating systems that support 
DOS calls of versions 2.0 and above. 

Exchange l\/louse IVIovement Vector 

For 8086-based systems, the application-dependent code is invoked 
via a CALL FAR (CALLF) instruction. On entry, the BX register contains 
the new x position of the mouse; the CX register contains the new y 
position of the mouse. When complete, the application-dependent 
code should perform a RETURN FAR (RETF) Instruction with the x,y 
position of the mouse the driver is to store In BX, CX. See vex_motv 
(7EH) in Section 7, "Input Functions," for information related to this 
function. 

Exchange Button Change Vector 

For 8086-based systems, the application code Is invoked via a CALL 
FAR (CALLF) Instruction with register AX containing the mouse button 
keys. Keys are encoded by the same rules that apply to the vq.mouse 
(7CH) function. When complete, the application-dependent code 
should perform a RETURN FAR (RETF) instruction with the mouse 
button state the driver is to store in AX. See vex.butv (7DH) for 
related information. Both vq_mouse and vex_butv are described in 
Section 7. 
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Exchange Cursor Change Vect or 

For 8086-based machines, the application-dependent code is invoiced 
with a CALL FAR (CALLF) instruction. Upon entry, register BX contains 
the X position and the CX register the y position at which the cursor is 
to be drawn. If the application-dependent code does not draw its own 
cursor, a CALL FAR should be performed to the address returned in 
control(9) and control(IO) with the x,y position at which to draw the 
cursor in BX, CX. This causes GEM VDI to draw a cursor. When 
complete, the application should perform a RETURN FAR (RETF) 
Instruction. See the description of vex_curv (7FH) in Section 7 for 
related information. 



Exchange Timer interrupt Vector 

For 8086-based systems, the application-dependent code is invoked 
with a CALL FAR (CALLF) instruction. When complete, the application 
should perform a RETURN FAR (RETF) instruction. 

See the description of vexjimv (76H) in Section 7 for related 
information. 
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68000-Specific Data 

Registers and TRAPS 

Pass the address of the Parameter Block to GEM VDI in one 32-bit 
register, DO.I. Register Dl.w contains the GEM VDI ID number 115 
(73H). 

For CP/M-68kJ** GEM VDI is invoked via TRAP 2. For other 68K 
operating systems that support GEM VDI, the TRAP is identified in the 
operating system's manual. 

Exchange Mouse Movement Vector 

For 68000-based systems, the application-dependent code is invoked 
via a JUMP TO SUBROUTINE (JSR) instruction. On entry, the DO.w 
register contains the new x position of the mouse. The Dl.w register 
contains the new y position of the mouse. When complete, the 
application-dependent code should perform a RETURN FROM 
SUBROUTINE (RTS) instruction with the x,y position of the mouse the 
driver is to store In DO.w, Dl.w. 

See vex_motv (7EH) in Section 7, "Input Functions," for related 
information. 



Exchange Button Change Vector 

For 68000 processors, the application code is invoked via a JUMP TO 
SUBROUTINE (JSR) instruction and DO.w contains the mouse button 
keys. Keys are encoded by the same rules that apply to vq.mouse 
(7CH). When complete, the application-dependent code should 
perform a RETURN FROM SUBROUTINE (RTS) instruction with the 
mouse button state the driver is to store in DO.w. 

See vex_butv (7DH) for related information. Both vq_mouse and 
vex_butv are described in Section 7. 
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Exchange Cursor Change Vect or 

For 68000-based machines, the application-dependent code is invoiced 
with a JUMP TO SUBROUTINE (JSR) instruction. Upon entry, the DO.w 
register contains the x position and the Dl.w register the y position. If 
the application-dependent code does not draw its own cursor, a JUMP 
TO SUBROUTINE (JSR) instruction should be performed to the address 
returned in control(9) and control(IO) with the x,y position at which to 
draw the cursor in DO.w and Dl.w. This causes GEM VDI to draw a 
cursor. When complete, the application should perform a RETURN 
FROM SUBROUTINE (RTS) instruction. 

Refer to the description of vex_curv (7FH) in Section 7 for related 
information. 



Exchange Timer Interrupt Vector 

The application-dependent code on 68000-based systems is invoked 
with a JUMP TO SUBROUTINE (JSR) instruction. When complete, the 
application should perform a RETURN FROM SUBROUTINE (RTS) 
instruction. 

Refer to the description of vex_tlmv (76H) in Section 7 for related 
information. 



End of Appendix E 
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Character Sets and Font Files 



Character Sets 

The system fonts provided with the VDI are illustrated in figures F-1 
and F-2. Figure F-1 shows the USASCII character set. Figure F-2 
shows the additional characters included to form the international 
character set. 

Note that external fonts (those which are dynamically loaded) do not 
include characters for decimal equivalents through 31; see "Font 
Format," in this appendix. 
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DMIMAI 
VAI HI 


^ 





16 


.52 


48 


64 


80 


96 


112 


-•■ 


lltXA 

nu iMAi 

VAI Uf 





1 


2 


3 


4 


5 


6 


7 










► 


niANK 
(SfA( ! 1 





@ 


P 


t 


P 


1 


1 


t 


< 


• 


1 


A 


Q 


a 


q 


2 


2 


1 


H 


// 


2 


B 


R 


h 


r 


3 


3 


"♦- 


■ 


# 


3 


C 


s 


c 


s 


4 


4 


^ 




$ 


4 


D 


1 


d 


t 


5 


5 


■ 




% 


5 


E 


u 


e 


u 


6 


6 


». 




& 


6 


F 


V 


f 


V 


7 


7 


♦ 




5 


7 


G 


w 


a 


w 


8 


8 


y 




( 


8 


H 


X 


h 


X 


9 


9 


G) 




) 


9 


I 


Y 


i 


y 


10 


A 


o 






• 
• 


J 


Z 


J 


z 


11 


B 


•r 




+ 


• 

5 


K 


[ 


k 


{ 


12 


C 


A 




9 


< 


L 


\ 


1 


1 


13 


D 


T 






z= 


M 


] 


m 


\ 


14 


E 


► 




. 


> 


N 


A 


n 


^\j 


15 


F 


< 




/ 


• 


O 




o 


A 



Figure F-1. GEM VDI USASCII Character Set 
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Character Sets 



VAIUF 


^ 


128 


144 


160 


176 


192 


208 


224 


240 


•9- 


llhXA 
DKIMAI 
VAI VV 


8 


9 


A 


B 


C 


D 


E 


F 








C 


E 


a 


a 


ij 




a 


= 


1 


1 


ii 


ae 


1 


o 


U 




& 


± 


2 


2 


e 


^ 


o 





^ 




r 


> 


3 


3 


a 


o 


u 









■K 


< 


4 


4 


a 


o 


ii 


oe 






S 


f» 


5 


5 


V 

a_ 


V 

o 


N 


CE 






a 


J 


6 


6 


o 

a 


u 


a 


A 






/* 


-r 


7 


7 


? 


V 

u 


o 


A 






T 




8 


8 


e 


y 


• 

6 


O 






<5 


O 


9 


9 


e 


• • 

o 


r- 


• • 









• 


10 


A 


e 


• • 

u 


1 


^ 






fi 


• 


11 


B 


i 


« 


1/2 


+ 






5 


r 


12 


C 


A 

1 


& 


1/4 


C^ 






^ 
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Figure F-2. GEM VDI International Character Set Extension 
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Font Format 

The system fonts and external fonts used in GEM VDI are composed of 
four parts: the font data, a font header, a character offset table, and a 
horizontal offset table. 

Font Data 

The font data is organized as a single raster area. The area's height 
equals the font height and its width equals the sum of the character 
widths. 

The top scan line of the first character in the font is aligned to a byte 
boundary. The top scan line of the second character is abutted to the 
first character and is not necessarily byte-aligned. That Is, the end of 
any character and the beginning of the following character often occur 
within the same byte; no byte alignment occurs within the font form. 

Bit padding occurs only at the end of a scan line. Each scan line in 
the font form begins on a word boundary. The number of bytes from 
the beginning of one scan line to the beginning of the next is called 
the form width. The number of scan lines required to draw any 
character is called the form height. 

The format of the file is such that the low byte of a word occurs in 
memory before the high byte. 

Font Header 

The font header contains information that describes global aspects of 
the font. Font global aspects include information that applies to every 
character of the font, for example, the name of the face, the font size, 
and the minimum and maximum characters in the font. The format of 
the font header is shown In Table F-1. 
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Font Header 


Table F-1. 


Font Header Format 




Byte Number Description 



- 1 Font identifier; see vst_font (15H) in Section 5 

2-3 Font size in points 

4-35 Font name; see vqt_name (82H) In Section 8 

36 - 37 Lowest ADE vaiue in the font, first character 

38 - 39 Highest ADE vaiue in the font, last character 

40 - 41 *Top line distance 

42 - 43 *Ascent line distance 

44 - 45 *Half line distance 

46 - 47 *Descent line distance 

48 - 49 *Bottom line distance 

50 - 51 Width of the widest character in the font 

52 - 53 Width of the widest character cell in the face 

54 - 55 Left offset; see vqt_font_info (83H) In Section 8 

56 - 57 Right offset see vqtjontjnfo (83H) In Section 8 

58-59 Thickening; this is the number of pixels by which to 
widen thickened characters 

60 - 61 Underline size; this is the pixel-width of the underline 



^Distances are measured relative to the character baseline and are 
always a positive value (magnitude rather than offset). 
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Table F-1. (Cont'd) 



Byte Number Description 



62-63 Lightening mask; this masic is used to drop pixels out 

when lightening (usually 5555H) 

64 - 65 Skewing mask; this mask determines when additional 

character rotation is required to perform skewing 
(usually 5555H) 

66 - 67 Flags: 

Bit Set if default system font 

Bit 1 Set if horizontal offset tables should be used 

Bit 2 Reservered — must be zero 

Bit 3 Set if mono-spaced font 

68 - 71 Pointer to the horizontal offset table 

72 - 75 Pointer to the character offset table 

76-79 Pointer to the font data 

80 - 81 Form width (see "Font Data") 

82 - 83 Form height (see "Font Data") 

84 - 87 Pointer to the next font (set by the driver) 

Character Offset 

The character offset table is used to index into the font data and to 
determine the width of specific characters in the font. It is indexed by 
relative character value (the ADE value of the desired character, minus 
the lowest ADE value in the font) and yields the offset from the base 
of the font data to the beginning of the character definition. The 
difference between the offset to a character and the offset to the 
following character gives the width of the character. Note that the 
character offset table includes one more entry than the number of 
characters in the font so that a width may be obtained for the final 
character in the font. 

Note: The character offset table is required even for mono-spaced 
fonts. 



F-6 



GEM VDI Reference Guide Character Offset 



Horizontal Offset Table 

The horizontal offset table is indexed by relative character value and 
yields any additional positive or negative spacing necessary before 
outputting the character. The horizontal offset table often does not 
exist; this is indicated by the horizontal offset table bit in the Flags 
word (66) of the font header. 



End of Appendix F 
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Bit Image File Format 



A GEM VDI bit image file contains information that can be used to re- 
create a picture from its bit (pixel) image. The file consists of a 
header and raw pixel information. The pixel information can be 
encoded in a variety of formats. 

A bit image file has an extension of IMG. 

Bit Image File Header 

The bit image file header consists eight 16-bit words in which the 
high order byte precedes the low order byte. The header words are 
defined as listed in Table G-1. 

Table G-1. Bit Image File Header Format 

Word Contents 

Image file version number 

1 Header length in words 

2 Number of planes (source device bits per pixel) 

3 Pattern definition length (number of bytes) 

4 Source device pixel width (microns) 

5 Source device pixel height (microns) 

6 Scan line width (pixels) 

7 Number of scan line items 



Word 1 indicates how long the header is. Always check this value; 
future releases of GEM might have a longer header. 

Word 3 defines the number of bytes used to describe pattern.run 
(pattern_run Is described below). The value can range from 1 to 8. 
Note that this value is 2 for most bit image files taken from screen 
devices. 
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Bit Image File Data Format 

The bit image data is composed of a series of scan line items. Word 7 
in the file header indicates how many scan line items are present. 

Each scan line item has two components: 

• a vertical replication count 

• encoded data for each plane 

The vertical replication count is a word value formatted as follows: 
Byte Contents 






NUL 


1 


NUL 


2 


FF Hex 


3 


Count 



The count indicates how many identical scan lines are defined in this 
scanjine item. 

The encoded data for each color plane follows the vertical replication 
count. The data is presented in the following order: 

first plane — red 
second plane — green 
third plane — blue 
fourth plane — grey 

Data is always provided for all defined bit planes. 

Note: The number of pixels described for each bit plane of a scan line 
is not necessarily the scan line width specified in the file header. 
Because the data is encoded in byte-wide packets (groups of eight 
pixels), the number of pixels actually described is always a multiple of 
eight and is never more than seven pixels wider than the scan line 
width. 
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Piane data is encoded in one of three modes: solid run, pattern run, or 
bit string. 

A solid.run item contains a single byte that describes a state and the 
number of bytes for which that state is true. The high-order bit 
defines the state where: 

1 = pixels on 
= pixels off 

The low-order seven bits define the run length. For example, to set a 
stream of 24 pixels (3 bytes) on, the encoded data is 83H. Similarly, to 
set a stream of 256 pixels (32 bytes) off, the encoded data is 20H. 

A pattern.run item describes a set of pattern bytes and the number of 
times the pattern bytes should be repeated. The number of bytes in a 
pattern is defined in the bit image file header; typically, it is two for a 
screen device image. A pattern_run item is defined as follows: 

Byte Contents 

NUL 

1 Length of run 

2 First byte of pattern 



Last byte of pattern 

(n is defined by header word 3) 



For example, a stream of 48 pixels (6 bytes) alternating red and blue 
with a pattern width of two is encoded as follows: 

• Red plane item (hex values): 00 03 AA AA 

• Blue plane item (hex values): 00 03 55 55 

• Green plane item: The green bit plane in this example is a solid 
run so the encoded data is 06H (all pixels are off). 



G-3 



Bit Image File Data Format GEM VDI Reference Guide 

If a stream of pixels for a given plane cannot be encoded efficiently as 
a solid run or pattern run, it must be encoded as a bit_string. A 
bit.string item is defined as follows: 

Byte Contents 

80 Hex 

1 Byte count 

2 First byte of bit string 



Last byte of bit string 



End of Appendix G 
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8086-speclflc data, E-1 
68000-spGclflc data, E-3 



Absolute mode, 5-19 

Alpha cursor control, 9-6, 9-7, 

9-8, 9-9, 9-10, 9-13, 

9-17 
Alpha Cursor Down, v_curdown, 

9-7 
Alpha Cursor Left, v_curleft, 9-9 
Alpha cursor position, 9-17 
Alpha Cursor Right, v_curright 

9-8 
Alpha Cursor Up, v_curup, 9-6 
Alpha text attribute, 9-15, 9-16 
Alpha text string output, 9-14 
Angle specifications, 4-15 
Arc, v_arc, 4-17 
Arrays, 1-5 
Ascent line, 5-32 
ASCII values, D-1 
Assembly language routines, 

2-11 
ASSIGN.SYS, 1-4, 3-18 
ASSIGN.SYS error messages, 

A-1 
Assignment table, 1-4 
Attribute functions, 5-2 



Attribute shadow, C-7, C-8 
Axis scaling, 9-26 



B 



Background color, 3-4, 3-13 

Bar, v_bar, 4-16 

Baseline, 5-31 

Baseline vector, 5-23 

Bit image encoding modes, G-3 

Bit image file, 9-26 

Bit image file 

color planes, G-2 

data, G-1, G-2 

file header, G-1 

version, G-1 
Bit string encoding, G-3 
Bottom line, 5-32 



Cell Array, v.cellarray, 3-8, 4-12 
Change GEM VDI Filename, 

vmjilename, 9-47 
Character baseline, 5-19 
Character cell, 5-19 
Character codes, D-1 
Character height, 3-9 
Character offset table, F-6 
Character rotation support, 8-15 
Character scan line, F-4 
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Character sets, F-1 
Character size, 5-21 
Character thickening, F-5 
Character top line, 5-19 
Character width, 3-9 
Circle, v_circle, 4-21 
Clear device, 3-13 
Clear Display List, 

v_clear_dispjist, 9-25 
Clear Workstation, v_clrwk, 3-13 
Clipping rectangle, 3-20, 8-17 
Close events, 3-12 
Close Virtual Workstation, 

v_clsvwk, 3-17 
Close Workstation, v_clswk, 

3-12 
Color index, pixel, 6-9 
Color table index values, 3-4 
Command line error messages, 

A-1 
Command, GEMVDI, 2-15 
Contour Fill, v_contourfill, 4-29, 

8-15 
Control, 2-11 
Control array, 1-5, 2-11 
Control functions, 3-1 
Coordinate scaling, 1-2 
Coordinate systems, 1-6, 6-6 
Coordinate window, C-2, C-3 
Copy Raster, Opaque, 

vro_cpyfm, 6-10 
Copy Raster, Transparent, 

vrt_cpyfm, 6-13 
CP/M-68K, E-3 
Cursor mask, 7-20 



Default values 

character baseline rotation, 
3-3 

character height, 3-3 

clipping, 3-3 

color index, 3-4 

cursor, 3-3 

fill parameter visibility, 3-3 

input mode, 3-3 

line width, 3-3 

marker height, 3-3 

polyline end style, 3-3 

text alignment, 3-3 

text style, 3-3 

user-defined fill pattern, 3-3 

user-defined line style, 3-3 

writing mode, 3-3 
Descent line, 5-32 
Device driver names, 1-4 
Device Drivers, 1-2 
Device handle, 1-3, 3-2 
Device ID number, 1-4, 3-5 
Device type, 3-9 
Device-specific information, 

8-14 
Direct Alpha Cursor Address, 

vs_curaddress, 9-13 
Disable/enable Film Exposure, 
vsc.expose, 9-44 



Echo mode, 7-16, 7-18 
Ellipse, v_ellipse, 4-22 
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Elliptical Arc, v_ellarc, 4-23 
Elliptical Pie, v.ellple, 4-24 
End Draw Area Type Primitive, 

C-10 
End-of-metafile marker, B-5 
Enter Alpha Mode, v_enter_cur, 

9-5 
Entering alpha mode, 9-5 
Entering graphics mode, 9-4 
Erase to End of Alpha Screen, 

v_eeos, 9-11 
Erase to End of Alpha Text Line, 

v_eeol, 9-12 
Error messages, A-1 
Escape functions, 9-1 
Exchange Button Change Vector 

(68000), E-3 
Exchange Button Change Vector 

(8086), E-1 
Exchange Button Change Vector, 

vex.butv, 7-28 
Exchange Cursor Change Vector 

(68000), E-4 
Exchange Cursor Change Vector 

(8086), E-2 
Exchange Cursor Change Vector, 

vex_curv, 7-32 
Exchange Mouse Movement 

Vector (68000), E-3 
Exchange Mouse Movement 

Vector (8086), E-1 
Exchange Mouse Movement 

Vector, vex_motv, 7-30 
Exchange Timer Interrupt Vector 

(68000), E-4 
Exchange Timer Interrupt Vector 

(8086), E-2 



Exchange Timer Interrupt 

Vector, vexJImv, 7-22 

Execute graphics commands, 
3-14 

Exit Alpha Mode, v_exit_cur, 9-4 

Exposure time, 9-41 

Extended Inquire, vq.extnd, 8-14 

External fonts, F-4 



Face values, 5-25 

Fill interior style, 5-33 

Fill perimeter attribute, 4-10 

Fill Rectangle, vr.recfl, 4-30 

Filled Area, vjlllarea, 3-8, 4-10 

Filled Rounded Rectangle, 

v.rfbox, 4-26 
Film name, 9-42 
Film type, 9-41 
Flood fill, 4-29 
Font 

ADE values, F-5 

ascent line distance, F-5 

bottom line distance, F-5 

byte-orlentatlon, F-6 

character offset table, F-6 

data, F-4 

descent line distance, F-5 

form height, F-4 

form width, F-4 

format F-4 

global aspects, F-4 

half line distance, F-5 

header, F-4 

horizontal offset table, F-6, 



lndex-3 



F-7 

identifier, F-5 

lightening masic, F-6 

raster area, F-4 

size in points, F-5 

sinewing masic, F-6 

top line distance, F-5 

underline size, F-5 
Font identifiers, 3-18 
Fonts, 3-18, 3-19 
Fornn Advance, v_form_adv, 9-22 
Function parameter format, 2-11 



GDOS, 1-2 

GDP attributes, 3-8 

GDP ID numbers, 4-14 

GDPs, 3-7 

GEM Draw, C-4 

GEIVI file extension, 9-47 

GEIVI Output, C-1 

GEMFILE.GEM, 9-47 

GEMVDI command, 2-15 

Generalized Drawing Primitives, 

3-7, 4-14 
Generate Tone, v_sound, 9-34 
Get Pixel, v_getj3ixel, 6-9 
Graphic cursor control, 9-20, 

9-21 
Group sub-function, C-5 



H 



Half line, 5-32 



Handle, 3-2 
Handle 

root device, 3-15 
Hard Copy, v_hardcopy, 9-19 
Hide Cursor, v_hide_c, 7-26 
Home Alpha Cursor, v_curhome, 

9-10 
Horizontal offset table, F-6, F-7 



I 



ID number 

device, 3-5 
IMG file extension, G-1 
Initiating printer output, 3-14 
Input Choice, Request Mode, 

vrq_choice, 7-13 
Input Choice, Sample Mode, 

vsm_choice, 7-14 
Input functions, 7-1 
Input Locator, Request Mode, 

vrqjocator, 7-5 
Input Locator, Sample Mode, 

vsmjocator, 7-7 
Input modes, 7-1 
Input parameters array, 1-5, 

2-11 
Input point coordinates array, 

1-5, 2-11 
Input String, Request Mode, 

vrq_string, 7-16 
Input String, Sample Mode, 

vsm_string, 7-18 
Input Valuator, Request Mode, 

vrq_valuator, 7-9 
Input Valuator, Sample Mode, 
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vsm_valuator, 7-11 
Inqulde Functions, 8-1 
Inquire Addressable Alpha 

Character Cells, 

vq_chcells, 9-3 
Inquire Camera Film Name, 

vqpjilmname, 9-42 
Inquire Cell Array, vq_cellarray, 

8-4 
Inquire Character Cell Width, 

vqt_width, 8-22 
Inquire Color Representation, 

vq_color, 8-2 
Inquire Current Alpha Cursor 

Address, vq.curaddress, 

9-17 
Inquire Current Fill Area 

Attributes, vqf_attributes, 

8-10 
Inquire Current Font 

Information, vqt_fontJnfo, 

8-26 
Inquire Current Graphic Text 

Attributes, vqt_attributes, 

8-12 
Inquire Current Polyline 

Attributes, vqLattributes, 

8-6 
Inquire Current Polymarker 

Attributes, vqm_attributes, 

8-8 
Inquire Font Name and Index, 

vqt_name, 8-24 
Inquire Input Mode, vqin.mode, 

8-18 
Inquire Justified Graphics Text, 

vqtjustified, 8-29 



Inquire Printer Scan Heights, 

vq_scan, 9-29 
Inquire Tablet Dimensions, 

vqjdimensions, 9-39 
Inquire Tablet Status, 

vq.tabstatus, 9-18 
Inquire Text Extent, vqt_extent, 

8-19 
Interrupts 
MS-DOS, E-1 
PC DOS, E-1 
IntIn, 2-11 
IntIn array, 2-11 
Intout 2-11 



Justified Graphics Text, 
vjustlfled, 4-27 



Keyboard definition, D-1 



Length of integer array, 2-14 

Length of intin array, 8-16 

Line style pattern word, 5-8 

Line type values, 5-8 

Line width, 3-10 

Load Fonts, vstjoadjonts, 3-18 

Locator terminator, 7-6 
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M 



N 



Marker height, 3-10 
Marker width, 3-10 
Maximum number of veritces, 

8-16 
Memory error messages, A-1 
Memory Form Definition Block, 

6-2 
Memory requirements, 2-16 
Metafile, 1-3, 3-14 
Metafile 
Metafile, 3-13 

extent values, B-4 

format, A-3 

header format, B-4 

item, B-1 

reserved sub-opcodes, C-1 

special escapes, B-6 
Metafile bounding rectangle, 

9-45 
Metafile extent values, 9-45 
Metafile item, 9-46 
Metafiles, 9-45, 9-46, 9-47 
Metaile header, 9-45 
MFDB, 6-2 

MFDB form format flag, 6-4 
Mouse 

button state, E-1, E-3 

position, E-1, E-3 
Mouse button state, 7-27 
Mouse form, 7-20 
MS-DOS registers and 

interrupts, E-1 
Muting flag, 9-35 



NDC, 1-6 
Normalized 

1-2 
Normalized 

1-6 
Number of 
Number of 

3-6 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 
Number of 



coordinate space. 

Device Coordinates, 

available colors, 3-8 
character heights, 

choice devices, 3-9 
colors, 8-15 
columns, 9-3 
faces, 3-7 
hatch styles, 3-7 
line types, 3-6 
line widths, 3-7 
locator devices, 3-8 
marker sizes, 3-7 
marker types, 3-7 
patterns, 3-7 
rows, 9-3 
string devices, 3-9 
valuator devices, 3-9 



Offset 
character, F-6 
horizontal, F-7 

Opcode 
1H, v_opnwk, 3-2 
2H, v.clswk, 3-12 
3H, v_clrwk, 3-13 
4H, v.updwk, 3-14 
5-1H, vq.chcells, 9-3 
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5-2H, v_exit_cur, 9-4 
5-3H, v_enter_cur, 9-5 
5-4H, v_curup, 9-6 
5-5H, v.curdown, 9-7 
5-6H, v.currlght, 9-8 
5-7H, v_curleft, 9-9 
5-8H, v_curhome, 9-10 
5-9H, v_eeos, 9-11 
5-AH, v.eeol, 9-12 
5-BH, vs_curad dress, 9-13 
5-CH, v.curtext, 9-14 
5-DH, v_rvon, 9-15 
5-EH, v.rvoff, 9-16 
5-FH, vq.curaddress, 9-17 
5-10H, v_eeol, 9-18 
5-1 1H, v_hardcopv, 9-19 
5-1 2H, v.dspcur, 9-20 
5-13H, v.rmcur, 9-21 
5-14H, vjorm.adv, 9-22 
5-15H, v_output_window, 9-23 
5-1 6H, v_clear_disp_list 9-25 
5-17H, v.bitjmage, 9-26 
5-1 8H, vq.scan, 9-29 
5-19H, v_alpha_text 9-31 
5-3CH, vs_palette, 9-33 
5-3DH, v.sound, 9-34 
5-3EH, vs.mute, 9-35 
5-5 1H, vt.resolutlon, 9-36 
5-52H, vt.axis, 9-37 
5-53H, vt_origin, 9-38 
5-54H, vq_tdlmensions, 9-39 
5-55H, vt.alignment, 9-40 
5-5BH, vspjilm, 9-41 
5-5CH, vqp_fllmname, 9-42 
5-5DH, vsc_expose, 9-44 
5-62H, v_meta_extents, 9-45 
5-63H, v_wrlte_meta, 9-46 



5-64H, vmjilename, 9-47 
6H, v_pline, 4-4 
7H, v_pmarkGr, 4-6 
8H, v_gtext, 4-8 
9H, vjillarea, 4-10 
AH, v.cellarray, 3-8, 4-12 
B-1H, v.bar, 4-16 
B-2H, v_arc, 4-17 
B-3H, v_piesllce, 4-19 
B-4H, v_clrcle, 4-21 
B-5H, v.elllpse, 4-22 
B-6H, v_ellarc, 4-23 
B-7H, v.ellpie, 4-24 
B-8H, v_rbox, 4-25 
B-9H, v_rfbox, 4-26 
B-AH, vjustlfied, 4-27 
CH, vst.height, 5-19 
DH, vst.rotation, 3-8, 5-23 
EH, vs_color, 3-8, 5-6 
FH, vsLtype, 5-8 
10H, vsLwJdth, 5-11 
IIH, vsLcolor, 5-12 
12H, vsm.type, 5-15 
13H, vsm_helght, 5-17 
14H, vsm.color, 5-18 
15H, vstjont, 5-25 
16H, vst_color, 5-27 
17H, vsfjnterior, 5-33 
18H, vsf_style, 5-35 
19H, vsf.color, 5-38 
1AH, vq.color, 8-2 
IBH, vq_cellarray, 8-4 
1CH, vrqjocator, 7-5 
IDH, vrq.valuator, 7-9 
IDH, vsm_valuator, 7-11 
lEH, vrq_choice, 7-13 
lEH, vsm_choice, 7-14 
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1FH, vrq.strjng, 7-16 
IFH, vsm^string, 7-18 
20H, vswr_mode, 5-3 
21H, vsin.mode, 7-3 
23H, vqLattrlbutes, 8-6 
24H, vqm.attrlbutes, 8-8 
25H, vqf_attributes, 8-10 
26H, vqt.attributes, 8-12 
27H, vst.alignment 5-31 
64H, v.opnvwk, 3-15 
65H, v.clsvwk, 3-17 
66H, vq_extnd (66H), 8-14 
67H, v.contourfill, 4-29 
68H, vsf_perlmeter, 5-39 
69H, v_get_pixel, 6-9 
BAH, vst_effects, 5-28 
6BH, vst_point, 5-21 
6CH, vsLends, 5-13 
SDH, vro.cpyfm, 6-10 
6EH, vr.tmfm, 6-12 
6FH, vscjorm, 7-20 
70H, vsf.udpat, 5-40 
71 H, vsLudsty, 5-10 
72H, vr.recfl, 4-30 
73H, vqin.mode, 8-18 
74H, vqt.Gxtent, 8-19 
75H, vqt.width, 8-22 
76H, vexjimv, 7-22 
77H, vstjoadjonts, 3-18 
78H, vst.unloadjonts, 3-19 
79H, vrt.cpyfm, 6-13 
7AH, v_show_c, 7-24 
7BH, v_hide_c, 7-26 
7CH, vq_mouse, 7-27 
7DH, vex.butv, 7-28 
7EH, vex_motv, 7-30 
7FH, vex_curv, 7-32 



80H, vq.key.s, 7-34 
81 H, vs.clip, 3-20 
82H, vqt.name, 8-24 
83H, vqtjontjnfo, 8-26 
84H, vqtjustlfied, 8-29 

Opcodes, 1-3 
Opcodes 
for assembly language calls, 

2-11 
Open Virtual Workstation, 

v_opnvwk, 3-15 
Open Workstation, v_opnwk, 

3-2, 8-14 
Output Bit Image File, 

v.bltjmage, 9-26 
Output Cursor Addressable 

Alpha Text, v_curtext, 

9-14 
Output function fill attributes, 

4-3 
Output function line attributes, 

4-2 
Output function text attributes, 

4-3 
Output functions, 4-1 
Output parameters array, 1-5, 

2-11 
Output point coordinates array, 

1-5, 2-11 
Output Printer Alpha Text, 

v_alpha_text, 9-31 
Output Window, 

v_output_wlndow, 9-23 
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Parameter Block (PB), 2-11 
Parameter Block 

address (68000), E-3 

address (8086), E-1 

format, 2-11 
Pattern run encoding, G-3 
Pattern word, 5-8 
PB, 2-11 
PC DOS registers and interrupts, 

E-1 
Physical Page Size, C-2 
Pie, v_pleslice, 4-19 
Pixel aspect ration, 9-26 
Pixel color index, 6-9 
Pixel height, 3-6 
Pixel height of printer head 

pass, 9-29 
Pixel image, G-1 
Pixel width, 3-6 
Place Graphics Cursor, v_dspcur, 

9-20 
Plane data encoding, G-3 
Plotter buffer, 3-14 
Point size, 5-21 
Points mode, 5-21 
Polyline color index values, 3-4 
Polyline, v_pline, 4-4 
Polymarker type values, 5-15 
Polymarker, v_pmarker, 4-6 
Primitive ID numbers, 4-14 
Printer buffer, 3-14 
Printer display list, 9-22, 9-25 
Printer head passes per page, 

9-29 
Printer scan height, 9-29 



Ptsin, 2-11 
Ptsin array, 2-11 
Ptsout, 2-11 



Raster area, 6-2 
Raster area formats, 6-4 
Raster Coordinates, RC, 1-7 
Raster logic operations, 6-7 
Raster operation writing modes, 

6-13 
Raster operations, 6-1 
RC, 1-7 
Registers 
68000, E-3 
MS-DOS, E-1 
PC DOS, E-1 
Remove Last Cursor, v_rmcur, 

9-21 
Renaming a metafile, 9-47 
Replace mode, 5-3 
Request input mode, 7-1 
Required functions, 2-2 
Return string, 7-16, 7-18 
Reverse transparent mode, 5-4 
Reverse Video Off, v_rvoff, 9-16 
Reverse Video On, v_rvon, 9-15 
RGB, 5-6 
Root device handle, 3-15, 3-19, 

7-30, 7-32 
Rounded Rectangle, v_rbox, 

4-25 



lndex-9 



Sample input mode, 7-1 
Sample Keyboard State 

Information, vq_key_s, 

7-34 
Sample Mouse Button State, 

vq_mouse, 7-27 
Sample program, 2-17 
Scaling rectangle, 9-26 
Scan height division factor, 

9-29 
Scan line, F-4 
Screen type, 8-14 
Seed fill, 4-29 
Select Camera Film Type and 

Exposure, vspjilm, 9-41 
Select Palette, vs_palette, 9-33 
Set Attribute Shadow Off, C-8 
Set Attribute Shadow On, C-7 
Set Character Baseline Vector, 

vst_rotatlon, 5-23 
Set Character Cell Height, 

Points Mode, vst_point, 

5-21 
Set Character Height, Absolute 

Mode, vst_height, 5-19 
Set Clipping Rectangle, vs.clip, 

3-20, 8-16 
Set Color Representation, 

vs_color, 3-8, 5-6 
Set Fill Color Index, vsf_color, 

5-38 
Set Fill Interior Style, 

vsfjnterior, 5-33 
Set Fill Perimeter Visibility, 

vsf_perimeter, 5-39 



Set Fill Style Index, vsf_style, 

5-35 
Set Graphic Text Alignment, 

vst_alignment, 5-31 
Set Graphic Text Special Effects, 

vst.effects, 5-28 
Set Input Mode, vsln_mode, 7-3 
Set Mouse Form, vscjorm, 7-20 
Set No Line Style, C-6 
Set Polyline Color Index, 

vsl_color, 5-12 
Set Polyline End Styles, 

vsLends, 5-13 
Set Polyline Line Type, vsLtype, 

5-8 
Set Polyline Width, vsLwidth, 

5-11 
Set Polymarker Color Index, 

vsm_color, 5-18 
Set Polymarker Height, 

vsm_height, 5-17 
Set Polymarker Type, vsm_type, 

5-15 
Set Tablet Alignment, 

vt_alignment, 9-40 
Set Tablet Axis Resolution, 

vt_axls, 9-37 
Set Tablet Origin, vt_origin, 

9-38 
Set Tablet Resolution, 

vt_resolution, 9-36 
Set Text Color Index, vst_color, 

5-27 
Set Text Font, vstjont, 5-25 
Set User-defined Fill Pattern, 

vsf.udpat, 5-40 
Set User-defined Line Style, 
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vsLudsty, 5-10 
Set Writing Mode, vswr_mode, 

5-3 
Set/Clear IVIuting Flag, vs_mute, 

9-35 
Setting 

color index, 5-6 

exposure time, 9-41 

fill area perimeter, 5-39 

fill color, 5-38 

fill interior style, 5-33 

fill style, 5-35 

line color, 5-12 

line end style, 5-13 

line type, 5-8 

line width, 5-11 

marker color, 5-18 

marker height, 5-17 

marker type, 5-15 

text alignment, 5-31 

text color, 5-27 

text effects, 5-28 

text font, 5-25 

writing mode, 5-3 
Show Cursor, v_show_c, 7-24 
Solid run encoding, G-3 
Sound, 9-34 

Sound suppression, 9-35 
Special metafile escapes, B-6 
Stack requirements, 2-16 
Standard keyboard, D-1 
Start Draw Area Type Primitive, 

C-9 
Sub-opcodes, C-1 
Sub-opcodes 

Coordinate Window, C-3 

End Draw Area Type Primitive, 



C-10 
Group, C-5 

Physical Page Size, C-2 
Set Attribute Shadow Off, C-8 
Set Attribute Shadow On, C-7 
Set Draw Area Type Primitive, 

C-9 
Set No Line Style, C-6 
System fonts, F-4 



Table axes alignment, 9-40 

Table resolution, 9-36 

Terminator character, 7-6 

Text alignment, 5-31 

Text effect word, 5-28 

Text effects, 5-28, 8-15 

Text Rotation, vst.rotatlon, 3-8 

Text, v_gtext, 4-8 

Top line, 5-32 

Transform Mode, vr_trnfm, 6-12 

Transformation mode 0, 1-6 

Transformation mode 2, 1-7 

Transparent mode, 5-4 

TRAP instruction, 68000, E-3 



U 



Undefined character symbol, 

4-8, 4-27 
Unload Fonts, vst_unload_fonts, 

3-19 
Update Metafile Extents, 

v_meta_extents, 9-45 
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Update Workstation, v.updwk, 

3-14 
USASCII character set, F-1 
User-defined metafile item, 

9-46 



v_alpha_text, 9-31 
v_arc, 4-17 
v_bar, 4-16 
v_bitjmage, 9-26 
v.cellarray, 3-8, 4-12 
v_circle, 4-21 
v_clear_disp_list, 9-25 
v_clrwk, 3-13, 9-22, 9-25 
v_clsvwk, 3-17 
v.clswk, 3-12, B-5 
v_contourfill (67H), 8-15 
v_contourfill, 4-29 
v^curdown, 9-7 
v_curhome, 9-10 
v_curleft, 9-9 
v_currlght, 9-8 
v_curtext, 9-14 
v_curup, 9-6 
v_dspcur, 9-20 
v_eeol, 9-12 
v^eeos, 9-11 
v.ellarc, 4-23 
v_ellipse, 4-22 
v_ellpie, 4-24 
v_enter_cur, 9-5 
v_exit_cur, 9-4 
vjillarea, 3-8, 4-10 
v_form_adv, 3-13, 9-22 



v_get_pixel, 6-9 
v_gtext, 4-8 
v.hardcopy, 9-19 
v_hide_c, 7-24, 7-26 
vjustified, 4-27 
v_meta_extents, 9-45, B-4, B-6 
v.opnvwk, 3-15, 7-13, 7-14, 

7-26 
v.opnwk, 3-2, 7-13, 7-14, 7-26, 

8-14, B-4, C-3 
v_output_window, 9-23 
v_pieslice, 4-19 
v_pline, 4-4 
v_pmarker, 4-6 
v_pmarker attributes, 4-2 
v_rbox, 4-25 
v.recfl, 4-30 
v_rfbox, 4-26 
v_rmcur, 9-21 
v.rvoff, 9-16 
v_rvon, 9-15 

v_siiow_c, 7-20, 7-24, 7-26 
v.updwk, 3-14, 9-23 
v_write.meta, 9-46, B-6 
Valuator keys, 7-9 
Values 

ASCII, D-1 

ASCII Decimal Equivalent, F-5 

default attributes, 3-3 

device type, 3-9 

face, 5-25 

fill interior style, 5-33 

fill style, 5-36 

keyboard, D-1 

line ends, 5-13 

line points, 5-13 

line type, 5-8 
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metafile extent, B-4 

MFDB format flag, 6-4 

pixel-to-color-lndex, 6-4 

polymarker type, 5-15 

text effects, 5-28 
VDI entry point, 1-5 
VDI ID number 

68000, E-3 

8086, E-1 
VDI keyboard assignments, D-1 
vex_butv, 7-28, E-1, E-3 
vex.curv, 7-32, E-2, E-4 
vex_motv, 7-30, E-1, E-3 
vexjimv, 7-22, E-2, E-4 
virtual workstations, 3-15 
vm_fllename, 9-47, B-6 
vq_cellarray, 8-4 
vq.chcells, 9-3, 9-13, B-7 
vq_color, 8-2 
vq_curaddress, 9-17 
vq_extnd, 3-2, 3-20, 4-4, 4-6, 
4-8, 4-10, 4-27, 4-29, 
6-10, 8-14, 9-31 
vq_key_s, 7-34 
vq_mouse, 7-27, E-1, E-3 
vq_scan, 9-29 
vqjabstatus, 9-18 
vq_tdimensions, 9-39 
vqf_attributes, 8-10 
vqin_mode, 8-18 
vqLattrlbutes, 8-6, B-7 
vqm_attributes, 8-8 
vqpjilmname, 9-42 
vqt.attributes, 7-16, 7-18, 8-12 
vqt_extent, 8-19 
vqtjontjnfo, 8-26, F-5 
vqtjustlfied, 4-27, 8-29 



vqt_name, 8-24, F-5 
vqt.width, 8-22 
vrjrnfm, 6-4, 6-10, 6-12 
vro_cpyfm, 6-4, 6-6, 6-10 
vrq_cholce, 7-13 
vrqjocator, 7-5 
vrq_string, 7-16 
vrq_valuator, 7-9 
vrqstring, 7-18 
vrt_cpyfm, 6-4, 6-6, 6-13 
vs.cllp, 3-20, 4-3, 8-16 
vs.color, 3-8, 5-6, 8-2 
vs_curaddress, 9-13 
vs.mute, 9-35 
vs_palette, 9-33, 9-34 
vsc_expose, 9-44 
vscjorm, 7-20, 9-20 
vsf_color, 5-38 
vsfjnterlor, 5-33 
vsf_peri meter, 5-39 
vsf_style, 5-35 
vsf_udpat, 5-40 
vsin_mode, 7-3 
vsLcolor, 5-12 
vsLends, 5-13 
vsLtype, 5-8, C-6 
vsLudsty, 5-10 
vsLwidth, 5-11 
vsm_choice, 7-14 
vsm_color, 5-18 
vsm_height, 5-17 
vsmjocator, 7-7, 9-20 
vsm_string, 7-18 
vsm_type, 5-15 
vsm_valuator, 7-11 
vspjilm, 9-41 
vst.alignment, 5-31, 8-16 
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vst_color, 5-27 
vst_effects, 5-28 
vstjont, 5-25 
vst_hGight 5-19 
vstjoadjonts, 3-18, 9-31 
vst_polnt 5-21 
vst_rotatlon, 3-8, 5-23 
vst_unloacl_fonts, 3-19 
vswr_mode, 4-3, 5-3 
vt.alignment, 9-40 
vt_axls, 9-37 
vt_orlgin, 9-38 
vt_resolutlon, 9-36 



W 

Workstation default attribute 

values, 3-3 
Write IVIetafile Item, 

v_write_meta, 9-46 
Writing a justified text string, 

4-27 
Writing a text string, 4-8 
Writing modes, 5-3 



X 

XOR mode, 5-4 
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GEM^*^ VDI Function Reference Table 



Opcode 
Dec Hex Function and Binding 



v_opnwk( work_in, &handle, wori(_out) 
v_clswk( handle ) 
v_clrwk( handle ) 
v_updwk( handle ) 

vq_chcells( handle, &rows, &columns ) 

v_e)(it_cur( handle ) 

v_enter_cur( handle ) 

v-curup( handle ) 

v_curdown( handle ) 

v_currlght( handle ) 

v_curleft( handle ) 

v_curhome( handle ) 

v_eeos( handle ) 

v_eeot( handle ) 

vs_curaddress( handle, row, column ) 

v_curtext( handle, string ) 

v_rvon( handle ) 

v_rvoff| handle ) 

vq_curaddress( handle, &row, &column ) 

vq_tabstatus( handle ) 

v_hardcopy( handle ) 

v.dspcurl handle, x, y ) 

v_rmcur( handle ) 

v_fornn_adv( handle ) 

v_output_window( handle, xy ) 

v_clear_dispjist( handle ) 

v_bitjmage( handle, filename, aspect, x_scale, y_scale, 

h.align, v.align, xy ) 

vq_scan( handle, &g_height, &g_slices, &a_height, &a_slices, 

Sifactor ) 

v_alpha_text( handle, string ) 

vs_palette( handle, palette ) 
v_sound( handle, frequency, duration ) 
vs_mute( handle, action ) 

vt_resolution( handle, xres, yres, &xset, &yset) 
5-52 vt_axis( handle, xres, yres, &xset, &yset) 



1 


1 


2 


2 


3 


3 


4 


4 


5-1 


5-1 


5-2 


5-2 


5-3 


5-3 


5-4 


5-4 


5-5 


5-5 


5-6 


5-6 


5-7 


5-7 


5-8 


5-8 


5-9 


5-9 


5-10 


5-A 


5-n 


5-B 


5-12 


5-C 


5-13 


5-D 


5-14 


5-E 


5-15 


5-F 


5-16 


5-10 


5-17 


5-11 


5-18 


5-12 


5-19 


5-13 


5-20 


5-14 


5-21 


5-15 


5-22 


5-16 


5-23 


5-17 


5-24 


5-18 


5-25 


5-19 


5-60 


5-3C 


5-61 


5-3D 


5-62 


5-3E 


5-81 


5-51 


5-82 


5-52 



Opcode 
Dec Hex Function and Binding 



5-83 5-53 vt_origin(handle. xorigin, yorigin) 

5-84 5-54 vq_tdimensions( handle, &xdimension. &ydimension) 

5-85 5-55 vt_allgnnnent( handle, dx, dy) 

5-91 5-5B vsp_film( handle, index, lightness ) 

5-92 5-5C vqp_filmname( handle, index, name ) 
5-93 5-5D vsc_expose( handle, state ) 

5-98 5-62 v_meta_extents( handle, min_x, min_v, nnax_x, max_y ) 
5-99 5-63 v_write_meta( handle, numjnts, ints, num_pts, pts ) 
5-100 5-64 vm_filename( handle, filename ) 

6 6 v_pline( handle, count, xy ) 

7 7 v_pmarker( handle, count, xy ) 

8 8 v_gtext( handle, x, y, string) 

9 9 v_fillarea( handle, count, xy) 

10 A v_cellarray( handle, xy, rowjength, eLper_row, num_rows, 

wr.mode, colors ) 

11-1 B-1 v_bar( handle, xy ) 

11-2 B-2 v_arc( handle, xc, yc, rad, sang, eang ) 

11-3 B-3 v_pieslice( handle, xc, yc, rad, sang, eang ) 

11-4 B-4 v_clrcle( handle, xc, yc, rad ) 

11-5 B-5 v_ellipse( handle, xc, yc, xrad, yrad ) 

11-6 B-6 v_ellarc( handle, xc, yc, xrad, yrad, sang, eang ) 

11-7 B-7 v_ellpie( handle, xc, yc, xrad, yrad, sang, eang) 

11-8 B-8 v_rbox( handle, xy ) 

11-9 B-9 v_rfbox( handle, xy ) 

11-10 B-A v_justified( handle, x, y, string, length, word_space, char.space) 

12 C vst_height( handle, height, &char_width, &char_height, &celLwidtl 

SicelLheight ) 

vst-rotation( handle, angle ) 
vs_color( handle, index, rgb ) 
vsLtype( handle, style ) 
vsl_width( handle, width ) 
vsl_color( handle, index ) 
vsm_type( handle, symbol ) 
vsm_height( handle, height ) 
vsm_color( handle, index ) 
vst_font( handle, font ) 



13 


D 


14 


E 


15 


F 


16 


10 


17 


11 


18 


12 


19 


13 


20 


14 


21 


15 



Opcode 


Dec 


Hex 


22 


16 


23 


17 


24 


18 


25 


19 


26 


1A 


27 


IB 


28 


1C 


28 


1C 


29 


ID 


29 


ID 


30 


IE 


30 


IE 


31 


IF 


31 


IF 


32 


20 


33 


21 


35 


23 


38 


24 


37 


25 


38 


26 


39 


27 


100 


64 


101 


65 


102 


66 


103 


67 


104 


68 


105 


69 


106 


6A 


107 


6B 


108 


6C 


109 


6D 


110 


6E 


111 


6F 



Function and Binding 



vst_color( handle, index ) 

vsfJnterior( handle, style ) 

vsf_stYle( handle. indoN ) 

vsf_color( handle, index ) 

vq_color( handle, index. set_flag. rgb ) 

vq_cellarrav( handle, xy, rowjen, num.rows. &aLused. &rows_used, 

&status, colarray ) 

vrqJocator( handle, initx, inity, &xout, &youl. &term ) 

vsmJocatorC handle, initx, inity, &xout, &yout. fiiterm ) 

vrq_valuator( handle, valjn, &val_out, Siterm ) 

vsm_vaiualor( handle, valjn, &vaLout, &term, fiistatus ) 

vrq_choice( handle, in_choice, &out_choice ) 

vsm_choice( handle, &choice ) 

vrq_string( handle, length, echo.mode, echo_xy, string) 

vsm_string( handle, length, echo_mode, echo_xy, string, &status ) 

vswr_mode( handle, mode ) 
vsin_mode( handle, dev.type, mode ) 

vql_attributes( handle, attributes ) 

vqm_attributes( handle, attributes ) 

vqf_attributes( handle, attributes ) 

vqt_attributes( handle, attributes ) 

vst_alignment( handle, horjn, vertjn, &hor_out, &vert_out ) 

v_opnvwi(( work_in, &handle, worl(_out ) 

v_clsvwk( handle ) 

vq_extnd( handle, owflag, work_out ) 

v_contourfill( handle, x, y, index ) 

vsf_perimeter( handle, per.vis ) 

v_gat_pixel( handle, x, y. &pel, &index ) 

vst_effect8( handle, effect ) 

vst_point( handle, point, &char_width, &char_height, &cell_width, 

&cell_height ) 

vsLendsl handle, beg_8tyle, end_styla) 

vro_cpyfm( handle, wr_mode, xy. srcMFDB, desMFDB ) 

vr_trnfm( handle, srcMFDB, desMFDB ) 

vsc_form( handle, cur.form ) 



Opcode 


Dec 


Hex 


112 


70 


113 


71 


114 


72 


lis 


73 


116 


74 


117 


75 


118 


76 


119 


77 


120 


78 


121 


79 


122 


7A 


123 


7B 


124 


7C 


125 


70 


126 


7E 


127 


7F 


128 


80 


129 


81 


130 


82 


131 


83 



Function and Binding 



vsf_udpat( handle. filLpat. planes ) 
vsLudsty( handle, pattern ) 
vr_recfl( handle, xy ) 

vqin_mode( handle. dev_type, &input_mode ) 
vqt_extent| handle, string, extent ) 

vqt-width( handle, character, SicelLwidth. &left-delta, &right_deita ) 
vex_timv( handle, tim.addr, &old_addr. &scale ) 
vstJoad_fonts( handle, select ) 
vst_unload_fonts( handle, select I 

vrt_cpyfm( handle, wr_mode, xy, srcMFOB, desMFOB, &lndeN ) 
v_show_c( handle, reset ) 
v_hide_c( handle ) 

vq_mouse( handle, &status, &px, &py ) 
vex_butv( handle, usercode. &savecode ) 
vex_motv( handle, usercode, &savecode ) 
vex_curv( handle, usercode, &savecode ) 
vq_key_s( handle. &status ) 
vs_clip( handle, clip.flag, xy ) 
vqt_name( handle, element_num, name ) 

vqt_fontJnfo( handle, &minADE. &maxADE, distances. Stmaxwidth, 
effects ) 
132 84 vqt_justified( handle, x, y, string, length, word_space. 

char_space. offsets ) 



